rhombus-node-mcp 0.1.56 → 0.1.57

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

@@ -1,4 +1,4 @@
-import { getDoorControllerRules, createDoorControllerRule, getDoorPolicies, createDoorPolicy, } from "../api/door-tool-api.js";
+import { getDoorControllerRules, createDoorControllerRule, getDoorControllerRule, updateDoorControllerRule, deleteDoorControllerRule, getDoorPolicies, createDoorPolicy, updateDoorPolicy, deleteDoorPolicy, } from "../api/door-tool-api.js";
 import { DoorToolRequestType, OUTPUT_SCHEMA, TOOL_ARGS, } from "../types/door-tool-types.js";
 import { createToolStructuredContent, createToolTextContent, extractFromToolExtra, } from "../util.js";
 const TOOL_NAME = "door-tool";
@@ -8,8 +8,14 @@ This tool manages Rhombus door controller rules and door policies.
 It has the following modes of operation, determined by the "requestType" parameter:
 - ${DoorToolRequestType.GET_DOOR_CONTROLLER_RULES}: Get all rules for a specific door controller. Requires doorControllerUuid.
 - ${DoorToolRequestType.CREATE_DOOR_CONTROLLER_RULE}: Create a new rule for a door controller. Requires doorControllerUuid and ruleConfig (JSON string).
+- ${DoorToolRequestType.UPDATE_DOOR_CONTROLLER_RULE}: Change an existing rule. Requires doorControllerUuid, ruleUuid and ruleConfig; ruleConfig is merged over the rule's current configuration.
+- ${DoorToolRequestType.DELETE_DOOR_CONTROLLER_RULE}: Delete a rule. Requires doorControllerUuid, ruleUuid and confirmDelete.
 - ${DoorToolRequestType.GET_DOOR_POLICIES}: Get all door alert policies in the organization.
 - ${DoorToolRequestType.CREATE_DOOR_POLICY}: Create a new door policy. Requires policyName and policyConfig (JSON string).
+- ${DoorToolRequestType.UPDATE_DOOR_POLICY}: Rename a door policy and/or change its configuration. Requires policyUuid plus policyName and/or policyConfig.
+- ${DoorToolRequestType.DELETE_DOOR_POLICY}: Delete a door policy. Requires policyUuid and confirmDelete.
+
+Door rules and policies govern physical access. Deleting or disabling one can leave a door permanently unlocked or permanently locked, so state what will change and get explicit confirmation before any update or delete.
 
 Use the get-entity-tool to find door controller and access controlled door UUIDs.
 `;
@@ -47,6 +53,128 @@ const TOOL_HANDLER = async (args, _extra) => {
                 const createdPolicy = await createDoorPolicy(config, requestModifiers, sessionId);
                 return createToolStructuredContent({ createdPolicy });
             }
+            case DoorToolRequestType.UPDATE_DOOR_POLICY: {
+                if (!args.policyUuid) {
+                    return createToolTextContent("policyUuid is required for update-door-policy.");
+                }
+                if (!args.policyName?.trim() && !args.policyConfig) {
+                    return createToolTextContent("update-door-policy needs at least one of policyName or policyConfig — both were empty, so there is nothing to change.");
+                }
+                // Parse before reading anything, so malformed JSON costs no calls and is
+                // unambiguously safe to retry.
+                let configPatch = {};
+                if (args.policyConfig) {
+                    try {
+                        const parsed = JSON.parse(args.policyConfig);
+                        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                            return createToolTextContent(`RETRYABLE — nothing was changed. policyConfig must be a JSON object describing the door policy; received ${Array.isArray(parsed) ? "an array" : typeof parsed}.`);
+                        }
+                        configPatch = parsed;
+                    }
+                    catch (parseError) {
+                        return createToolTextContent(`RETRYABLE — nothing was changed. policyConfig is not valid JSON (${parseError instanceof Error ? parseError.message : "parse error"}).`);
+                    }
+                }
+                // updateDoorPolicy REPLACES the policy object, so merge over the current
+                // one rather than sending the patch alone.
+                const policies = await getDoorPolicies(requestModifiers, sessionId);
+                const existing = policies.find(policy => policy.uuid === args.policyUuid);
+                if (!existing) {
+                    return createToolTextContent(`No door policy in this organization has the uuid "${args.policyUuid}". Use get-door-policies to see the policies that exist — do not guess a uuid.`);
+                }
+                const { success, warningMsg } = await updateDoorPolicy({
+                    ...existing,
+                    ...configPatch,
+                    uuid: args.policyUuid,
+                    name: args.policyName?.trim() || existing.name,
+                }, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    updated: { success, uuid: args.policyUuid },
+                    warningMsg,
+                    note: `Updated the door policy "${args.policyName?.trim() || existing.name || args.policyUuid}". Fields not included in policyConfig kept their previous values. This changes how every door on this policy behaves.`,
+                });
+            }
+            case DoorToolRequestType.DELETE_DOOR_POLICY: {
+                if (!args.policyUuid) {
+                    return createToolTextContent("policyUuid is required for delete-door-policy.");
+                }
+                const policies = await getDoorPolicies(requestModifiers, sessionId);
+                const existing = policies.find(policy => policy.uuid === args.policyUuid);
+                if (!existing) {
+                    return createToolTextContent(`No door policy in this organization has the uuid "${args.policyUuid}". Use get-door-policies to see the policies that exist.`);
+                }
+                if (!args.confirmDelete) {
+                    return createToolStructuredContent({
+                        doorPolicies: [existing],
+                        note: `NOT DELETED — nothing was changed. Deleting the door policy "${existing.name ?? args.policyUuid}" is irreversible and ` +
+                            `removes the alerting rules from every door using it. Tell the user what will stop being monitored and get explicit ` +
+                            `confirmation, then call this tool again with confirmDelete: true.`,
+                    });
+                }
+                const { success, uuid, warningMsg } = await deleteDoorPolicy(args.policyUuid, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    deleted: { success, uuid },
+                    warningMsg,
+                    note: `Deleted the door policy "${existing.name ?? args.policyUuid}". Doors that used it no longer have its alerting rules.`,
+                });
+            }
+            case DoorToolRequestType.UPDATE_DOOR_CONTROLLER_RULE: {
+                if (!args.doorControllerUuid || !args.ruleUuid) {
+                    return createToolTextContent("doorControllerUuid and ruleUuid are both required for update-door-controller-rule — a rule is addressed by controller AND rule uuid.");
+                }
+                if (!args.ruleConfig) {
+                    return createToolTextContent("ruleConfig is required for update-door-controller-rule.");
+                }
+                let configPatch;
+                try {
+                    const parsed = JSON.parse(args.ruleConfig);
+                    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                        return createToolTextContent(`RETRYABLE — nothing was changed. ruleConfig must be a JSON object describing the rule; received ${Array.isArray(parsed) ? "an array" : typeof parsed}.`);
+                    }
+                    configPatch = parsed;
+                }
+                catch (parseError) {
+                    return createToolTextContent(`RETRYABLE — nothing was changed. ruleConfig is not valid JSON (${parseError instanceof Error ? parseError.message : "parse error"}).`);
+                }
+                // updateDoorControllerRule REPLACES the rule, so merge over the current one.
+                const existing = await getDoorControllerRule(args.doorControllerUuid, args.ruleUuid, requestModifiers, sessionId);
+                if (!existing) {
+                    return createToolTextContent(`Door controller ${args.doorControllerUuid} has no rule with the uuid "${args.ruleUuid}". Use get-door-controller-rules for that controller to see its rules.`);
+                }
+                const { success } = await updateDoorControllerRule(args.doorControllerUuid, { ...existing, ...configPatch, uuid: args.ruleUuid }, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    updated: { success, uuid: args.ruleUuid },
+                    note: `Updated rule "${existing.name ?? args.ruleUuid}" on door controller ${args.doorControllerUuid}. Fields not included in ruleConfig kept their previous values. This changes the physical behaviour of the door.`,
+                });
+            }
+            case DoorToolRequestType.DELETE_DOOR_CONTROLLER_RULE: {
+                if (!args.doorControllerUuid || !args.ruleUuid) {
+                    return createToolTextContent("doorControllerUuid and ruleUuid are both required for delete-door-controller-rule.");
+                }
+                const existing = await getDoorControllerRule(args.doorControllerUuid, args.ruleUuid, requestModifiers, sessionId);
+                if (!existing) {
+                    return createToolTextContent(`Door controller ${args.doorControllerUuid} has no rule with the uuid "${args.ruleUuid}", so there is nothing to delete.`);
+                }
+                if (!args.confirmDelete) {
+                    return createToolStructuredContent({
+                        doorControllerRules: [
+                            {
+                                uuid: existing.uuid ?? undefined,
+                                name: existing.name ?? undefined,
+                                deviceUuid: args.doorControllerUuid,
+                            },
+                        ],
+                        note: `NOT DELETED — nothing was changed. Deleting rule "${existing.name ?? args.ruleUuid}" from door controller ` +
+                            `${args.doorControllerUuid} is irreversible and changes how that door physically behaves — it can leave the door ` +
+                            `unlocked or locked outside its schedule. Confirm with the user, then call this tool again with confirmDelete: true.`,
+                    });
+                }
+                const { success, uuid } = await deleteDoorControllerRule(args.doorControllerUuid, args.ruleUuid, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    deleted: { success, uuid },
+                    note: `Deleted rule "${existing.name ?? args.ruleUuid}" from door controller ${args.doorControllerUuid}.`,
+                });
+            }
         }
     }
     catch (error) {
@@ -63,6 +191,6 @@ export function createTool(server) {
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS,
         outputSchema: OUTPUT_SCHEMA.shape,
-        annotations: { readOnlyHint: false, destructiveHint: false },
+        annotations: { readOnlyHint: false, destructiveHint: true },
     }, TOOL_HANDLER);
 }

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

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

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

@@ -1,28 +1,9 @@
 import { getElementsBadgeTimeline } from "../api/elements-badge-timeline-tool-api.js";
 import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/elements-badge-timeline-tool-types.js";
 import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
+import { buildBadgeTimelineToolDescription } from "../types/badge-timeline-tool-types.js";
 const TOOL_NAME = "elements-badge-timeline-tool";
-const TOOL_DESCRIPTION = `
-Reconstructs one person's movements through a building from their Honeywell Elements (LenelS2 Elements) 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 Elements (LenelS2 Elements)");
 const TOOL_HANDLER = async (args, _extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
     try {

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

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

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

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

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

@@ -1,4 +1,4 @@
-import { getAccessControlEvents, getBrivoAccessControlEvents, getEventsForEnvironmentalGateway, getClimateEventsForSensor, getComponentEventsByLocation, getCameraFootageSeekpointEvents, getButtonPressEvents, getOccupancyEvents, getProximityEvents, getDoorbellEvents, } from "../api/events-tool-api.js";
+import { getAccessControlEvents, getBrivoAccessControlEvents, getEventsForEnvironmentalGateway, getClimateEventsForSensor, getComponentEventsByLocation, describeEmptyComponentEventResult, getCameraFootageSeekpointEvents, getButtonPressEvents, getOccupancyEvents, getProximityEvents, getDoorbellEvents, } from "../api/events-tool-api.js";
 import { EventsToolRequestType, OUTPUT_SCHEMA, TOOL_ARGS, } from "../types/events-tools-types.js";
 import { createToolStructuredContent } from "../util.js";
 import { getLogger } from "../logger.js";
@@ -6,109 +6,21 @@ import { TempUnit } from "../utils/temp.js";
 const logger = getLogger("events-tool");
 const TOOL_NAME = "events-tool";
 // "faces" | "people" | "human" | "access-control"
+//
+// 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. Per-mode arguments, field semantics, and
+// enum catalogs live on the input-parameter descriptions (unbilled until the
+// tool is loaded, still in front of the model when it builds the call).
+// See PERF_MASTER_PLAN P2 #4a.
 const TOOL_DESCRIPTION = `
-**Scope:** This tool returns **raw, event-level data** (individual events with timestamps). Use **report-tool** when you need aggregated counts, time-series summaries, or analytics over intervals.
+**Raw, event-level records** — individual events, each with a timestamp. Modes are set by "eventType": access-control, brivo-access-control, environmental-gateway, climate-sensor, component-events, camera, button-press, occupancy, proximity, doorbell.
 
-**Vehicles vs lpr-tool:** **eventType "camera"** returns **footage seekpoints** from that camera's recording timeline—**every activity type** the API returns for the window (human motion, vehicle motion, and others depending on the camera and analytics). Some rows may include plate or vehicle metadata on the seekpoint. **lpr-tool** is still the right choice for **org LPR workflows**: saved vehicles, vehicle labels, fuzzy plate search, and vehicle event APIs—not a replacement for "everything this camera logged on its timeline."
+Use it when the user asks for specific events: unlocks, badge ins, credentials, arrivals, Brivo access control, door state changes, panic or doorbell button presses, environmental gateway readings, climate data (temperature, humidity, air quality, vape), occupancy counts, proximity tags, or a camera's timeline activity. For maximum flexibility across event types at a location, use eventType "component-events".
 
-This tool has multiple modes, set by "eventType": access-control, brivo-access-control, environmental-gateway, climate-sensor, component-events, camera. Use it when the user asks for specific events (unlocks, badge ins, credentials, arrivals, environmental readings, climate data, camera timeline activity, or other component events). It can return large result sets; keep time ranges narrow. For ranges spanning more than ~24 hours, prefer report-tool for aggregates. For maximum flexibility across event types at a location, use eventType "component-events".
-
----
-
-When eventType is "brivo-access-control":
-
-Retrieves badge/credential events from Brivo-integrated doors. Automatically fetches the Brivo integration configuration to determine which locations have Brivo doors mapped. No door UUIDs are required.
-
-Use this when the user asks specifically about Brivo events, Brivo badge ins, Brivo access control, or events from Brivo doors.
-
-Arguments:
-  * **startTime (string):** Start of the time range (ISO 8601).
-  * **endTime (string):** End of the time range (ISO 8601).
-
-Returns:
-  * **integrationEnabled:** Whether the Brivo integration is currently enabled.
-  * **brivoDoorsConfigured:** Number of Brivo doors configured in the integration.
-  * **brivoDoors:** List of Brivo doors with their IDs, names, and associated Rhombus location UUIDs.
-  * **events:** Credential received events from all locations that have Brivo doors configured, sorted newest first.
-
-Note: Events are fetched at the location level, so results may include events from all access-controlled doors at locations where Brivo is configured.
-
----
-
-When eventType is "access-control":
-
-Retrieves access control events (arrivals, badge ins, credentials, unlocks) for the given door(s). Can return a lot of data—use a narrow time range.
-
-Arguments:
-  * **accessControlledDoorUuids (array of strings):** UUIDs of the access-controlled doors.
-  * **startTime (string):** Start of the time range (ISO 8601).
-  * **endTime (string):** End of the time range (ISO 8601).
-
-The \`credSource\` field indicates how the event was triggered:
-  * **REMOTE:** Rhombus Key app remote unlock.
-  * **REMOTE (Admin):** Unlock via Rhombus console or browser/mobile app.
-  * **BLE_WAVE:** User waved hand over the reader.
-  * **NFC:** User tapped badge or phone on the reader.
-
----
-
-Retrieves environmental gateway events (sensor readings, derived values) for a device in a time range. Timestamps are in the **device** timezone, not necessarily UTC.
-
-Arguments:
-  * **deviceUuid (string):** UUID of the environmental gateway device.
-  * **startTime (string):** Start of range (ISO 8601).
-  * **endTime (string):** End of range (ISO 8601).
-
----
-
-When eventType is "climate-sensor":
-
-Retrieves climate sensor events (temperature, humidity, air quality, etc.) for a sensor in a time range. Timestamps are in the **sensor** timezone, not necessarily UTC.
-
-Arguments:
-  * **sensorUuid (string):** UUID of the climate sensor.
-  * **startTime (string):** Start of range (ISO 8601).
-  * **endTime (string):** End of range (ISO 8601).
-  * **limit (number, optional):** Max events to return. Default 1000.
-
----
-
-When eventType is "component-events":
-
-Retrieves all component event types for a location in a time range. Most flexible option; filter by event type via componentEventTypes. Timestamps are in the **location** timezone, not necessarily UTC.
-
-Arguments:
-  * **locationUuid (string):** UUID of the location.
-  * **componentEventTypes (array, optional):** Event types to include. If empty or omitted, returns all types.
-  * **startTime (string):** Start of range (ISO 8601).
-  * **endTime (string):** End of range (ISO 8601).
-
-Valid event types include:
-  * **DoorbellEvent:** Doorbell button press events
-  * **CredentialReceivedEvent:** Badge/credential scans (NFC, BLE_WAVE, REMOTE unlocks)
-  * **DoorStateChangeEvent:** Door state changes (locked/unlocked)
-  * **ButtonEvent:** Generic button press events
-  * **PanicButtonEvent:** Panic/emergency button activations
-  * **DoorReaderStateChangeEvent:** Changes in door reader state
-  * **DoorRelayStateChangeEvent:** Changes in door relay state
-  * **AccessControlUnitTamperEvent:** Tamper detection events
-  * **AccessControlUnitBatteryStateChangeEvent:** Battery state changes
-  * **WaveToUnlockIntentExpiredEvent:** Wave-to-unlock timeout events
-  * **DoorAuthFirstInStateEvent:** First-in authentication state events
-  * **DoorScheduleFirstInStateEvent:** First-in schedule state events
-  * And more (see input schema for full list).
-
----
-
-When eventType is "camera":
-
-Retrieves **footage seekpoints** for one camera: **all activity types** returned for the search window (not limited to human motion). Each item includes an **activity** string plus **timestamp**; plate/vehicle/face fields appear when the API provides them. Use **lpr-tool** for org LPR saved vehicles, labels, and dedicated plate search.
-
-Arguments:
-  * **cameraUuid (string):** UUID of the camera.
-  * **startTime (string):** Start of range (ISO 8601).
-  * **duration (number):** Search window in seconds. Default 3600 (1 hour).
+**Not this tool:** use **report-tool** for aggregated counts, time-series summaries, or analytics over intervals — including any range spanning more than ~24 hours. Use **lpr-tool** for org LPR workflows: saved vehicles, vehicle labels, fuzzy plate search, and vehicle event APIs. eventType "camera" returns that camera's own **footage seekpoints** — **every activity type** on its recording timeline (human motion, vehicle motion, and others depending on camera and analytics), sometimes carrying plate or vehicle metadata — which is not a replacement for lpr-tool's plate search.
 
+Result sets can be large: keep time ranges narrow. Per-mode required arguments, field semantics, and the full component-event-type list are documented on the input parameters.
 `;
 const TOOL_HANDLER = async (args, extra) => {
     const { eventType, accessControlledDoorUuids, deviceUuid, sensorUuid, locationUuid, componentEventTypes, startTime, endTime, limit, timeZone, tempUnit, cameraUuid, duration, buttonSensorUuid, occupancySensorUuid, proximityTagUuids, doorbellCameraUuid, } = args;
@@ -166,7 +78,16 @@ const TOOL_HANDLER = async (args, extra) => {
             }
             else {
                 const events = await getComponentEventsByLocation(locationUuid, componentEventTypes || [], startTime ? new Date(startTime).getTime() : undefined, endTime ? new Date(endTime).getTime() : undefined, timeZone, extra._meta?.requestModifiers, extra.sessionId);
-                return createToolStructuredContent({ eventType: "component-events", componentEvents: events });
+                // An empty result from a doorless location reads identically to "nothing
+                // happened" — say which it is rather than letting the model guess.
+                const note = events.length === 0
+                    ? await describeEmptyComponentEventResult(locationUuid, componentEventTypes || [], extra._meta?.requestModifiers, extra.sessionId)
+                    : undefined;
+                return createToolStructuredContent({
+                    eventType: "component-events",
+                    componentEvents: events,
+                    ...(note ? { note } : {}),
+                });
             }
         }
         case EventsToolRequestType.CAMERA: {