rhombus-node-mcp 0.1.55 → 0.1.57

package/dist/network/network.js

@@ -79,6 +79,81 @@ export function constructRequestHeaders(url, modifiers, sessionId // kept for AP
     }
     return { url, requestHeaders };
 }
+// Credential-bearing headers must never reach the log store (they were being
+// written verbatim to OpenSearch on every outbound call, prod included). The
+// session token also rides in the URL as `_rs`, so redact that too.
+const SENSITIVE_HEADERS = new Set([
+    "x-auth-apikey",
+    "x-auth-access-token",
+    "x-auth-session",
+    "cookie",
+]);
+function redactHeadersForLog(headers) {
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        out[key] = SENSITIVE_HEADERS.has(key.toLowerCase()) ? `<set, ${value.length} chars>` : value;
+    }
+    return out;
+}
+function redactUrlForLog(url) {
+    return url.replace(/([?&]_rs=)[^&]+/g, "$1<redacted>");
+}
+// The `status` string on a failed result is read by tools and relayed to the
+// model almost verbatim, so it has to be a short, readable sentence. It used to
+// be `JSON.stringify({body: <the entire request payload>, error: <raw text>})`,
+// which buried the one useful line in a copy of the request — and collapsed to
+// the literally useless "Request Error: {}" whenever the thrown value was an
+// Error (JSON.stringify of an Error yields "{}").
+const API_ERROR_DETAIL_LIMIT = 400;
+function truncateDetail(text) {
+    return text.length > API_ERROR_DETAIL_LIMIT
+        ? `${text.slice(0, API_ERROR_DETAIL_LIMIT)}…`
+        : text;
+}
+/** Pull the human-readable message out of an api2 error body (JSON or plain text). */
+function extractApiErrorDetail(responseText) {
+    const text = responseText.trim();
+    if (!text)
+        return "";
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object") {
+            // `msg` is what api2's request deserializer returns on a malformed body
+            // (e.g. {"msg":"JSON doesn't match expected object structure"}); without
+            // it here the whole JSON blob got dumped into the model-facing message.
+            for (const key of ["errorMsg", "message", "msg", "error", "status", "detail"]) {
+                const value = parsed[key];
+                if (typeof value === "string" && value.trim())
+                    return truncateDetail(value.trim());
+            }
+        }
+    }
+    catch {
+        // not JSON — fall through to the raw text
+    }
+    return truncateDetail(text);
+}
+function describeHttpFailure(status, responseText) {
+    const detail = extractApiErrorDetail(responseText);
+    return detail
+        ? `HTTP ${status}: ${detail}`
+        : `HTTP ${status} from the Rhombus API (the response body carried no error message)`;
+}
+/** JSON.stringify(new Error(...)) === "{}", so unwrap thrown values by hand. */
+function describeThrown(error) {
+    if (error instanceof Error) {
+        const cause = error.cause instanceof Error ? ` (cause: ${error.cause.message})` : "";
+        return `${error.name}: ${error.message}${cause}`;
+    }
+    if (typeof error === "string")
+        return error;
+    if (error && typeof error === "object") {
+        const serialized = JSON.stringify(error);
+        if (serialized && serialized !== "{}")
+            return truncateDetail(serialized);
+    }
+    return String(error ?? "unknown error");
+}
 export async function postApi({ route, body, modifiers, sessionId, }) {
     let url = BASE_URL + route;
     const { url: newUrl, requestHeaders } = constructRequestHeaders(BASE_URL + route, modifiers, sessionId);
@@ -88,25 +163,26 @@ export async function postApi({ route, body, modifiers, sessionId, }) {
         body = JSON.stringify(body);
     }
     try {
-        logger.info(`[POSTAPI] REQUEST - ${url} - ${body} - ${JSON.stringify(requestHeaders)}`);
+        logger.info(`[POSTAPI] REQUEST - ${redactUrlForLog(url)} - ${body} - ${JSON.stringify(redactHeadersForLog(requestHeaders))}`);
         const response = await fetch(url, {
             method: "POST",
             headers: requestHeaders,
             body,
         });
         if (!response.ok) {
-            logger.debug(`❌ RESPONSE - ${response.ok} - ${response.status}`);
+            const responseText = await response.text().catch(() => "");
+            // The request body belongs in the log, not in the message the model reads.
+            logger.error(`[POSTAPI] HTTP ${response.status} - ${redactUrlForLog(url)} - request: ${body} - response: ${truncateDetail(responseText)}`);
             if (response.status === 401 || response.status === 403) {
                 return {
                     error: true,
                     status: "Sorry, I don't have permission to help with this request.  Consider upgrading my permissions by changing the role of the API Key I am using.",
                 };
             }
-            throw {
-                body: JSON.parse(body),
-                error: await response.text(),
+            return {
+                error: true,
+                status: describeHttpFailure(response.status, responseText),
             };
-            // throw new Error(`HTTP error! status: ${response.status}`);
         }
         const ret = await response.json();
         const jsonStr = JSON.stringify(ret);
@@ -115,15 +191,51 @@ export async function postApi({ route, body, modifiers, sessionId, }) {
         return ret;
     }
     catch (error) {
-        logger.error(`[POSTAPI] ERROR - ${JSON.stringify(error || {}, null, 4)}`);
+        logger.error(`[POSTAPI] ERROR - ${redactUrlForLog(url)} - ${error instanceof Error ? (error.stack ?? error.message) : describeThrown(error)}`);
         return {
             error: true,
-            status: `Request Error: ${JSON.stringify(error)}`,
+            status: `Request failed before a response was received: ${describeThrown(error)}`,
         };
     }
 }
+/**
+ * api2 signals failure on TWO channels, and reading either one alone loses the
+ * message on the other:
+ *
+ *  - **Transport / HTTP** failures are synthesised by `postApi` above as
+ *    `{error: true, status: "<sentence>"}`. `status` is our field, not api2's.
+ *  - **Domain** failures come back on HTTP **200** with `{error: true,
+ *    errorMsg: "..."}` — api2's own in-band contract (734 response types in
+ *    `types/schema.ts` declare `error`, 732 declare `errorMsg`).
+ *
+ * So a handler that checks only `status` reports "API request failed." for every
+ * real api2 rejection ("that plate is already saved", "schedule not found"),
+ * leaving the model nothing to correct. Returns undefined when the call
+ * succeeded.
+ */
+export function apiFailureMessage(res) {
+    if (!res.error)
+        return undefined;
+    const detail = res.status?.trim() || res.errorMsg?.trim();
+    return detail || "The Rhombus API rejected the request without giving a reason.";
+}
+/**
+ * api2's `warningMsg` — the "it worked, but" channel. A call can succeed while
+ * reporting that part of it did not apply, and that caveat has to reach the
+ * user.
+ *
+ * Takes `unknown` so any response shape can be checked without a cast at the
+ * call site — the caveat should never be dropped just to satisfy the compiler.
+ */
+export function apiWarning(res) {
+    if (!res || typeof res !== "object")
+        return undefined;
+    const warning = res.warningMsg;
+    return typeof warning === "string" && warning.trim() ? warning.trim() : undefined;
+}
 export function throwIfApiError(res) {
-    if (res.error) {
-        throw new Error(res.status ?? "API request failed.");
+    const message = apiFailureMessage(res);
+    if (message) {
+        throw new Error(message);
     }
 }

package/dist/network/org-reference-cache.js

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { requestAuthContext } from "../auth-context.js";
+import { postApi } from "./network.js";
+/**
+ * Short-TTL cache for slow-changing org-reference fetches (device state
+ * lists, locations, org info). Within a single chatbot query the model
+ * routinely calls several tools that each re-fetch the same org-wide lists
+ * (e.g. entity-lookup's 11-way fan-out plus get-entity-tool plus a camera
+ * tool); this collapses those into one upstream call per route.
+ *
+ * - Keyed on hash(auth identity + route + body + modifiers). The auth
+ *   payload comes from requestAuthContext (AsyncLocalStorage) because
+ *   `extra.sessionId` is undefined in the stateless HTTP transport; when no
+ *   auth context is present we bypass the cache entirely rather than share
+ *   entries across unknown callers.
+ * - The IN-FLIGHT promise is cached, so concurrent callers (Promise.all
+ *   fan-outs) share one request. Failures are never cached: both a thrown
+ *   rejection AND an api2 in-band failure (`{error: true}` on HTTP 200 — see
+ *   apiFailureMessage) evict the entry. postApi resolves rather than throws on
+ *   those, so without the second check a single transient upstream error would
+ *   be replayed to every caller for the whole TTL.
+ * - TTL is deliberately short: staleness after a mutation (e.g. a camera
+ *   rename) is bounded at ORG_REFERENCE_TTL_MS.
+ */
+export const ORG_REFERENCE_TTL_MS = 60_000;
+const MAX_ENTRIES = 500;
+const cache = new Map();
+function evictIfNeeded(now) {
+    if (cache.size <= MAX_ENTRIES)
+        return;
+    for (const [key, entry] of cache) {
+        if (entry.expiresAt <= now)
+            cache.delete(key);
+    }
+    // Still over cap (many live sessions): drop oldest-inserted first.
+    while (cache.size > MAX_ENTRIES) {
+        const oldest = cache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        cache.delete(oldest);
+    }
+}
+/** Test hook / mutation hook: drop every cached entry. */
+export function clearOrgReferenceCache() {
+    cache.clear();
+}
+/**
+ * Drop-in replacement for postApi on org-reference routes. Do NOT use for
+ * mutations or fast-changing data.
+ */
+export function cachedPostApi(params, ttlMs = ORG_REFERENCE_TTL_MS) {
+    const auth = requestAuthContext.getStore();
+    if (!auth)
+        return postApi(params);
+    const key = createHash("sha256")
+        .update(JSON.stringify([auth, params.route, params.body ?? null, params.modifiers ?? null]))
+        .digest("hex");
+    const now = Date.now();
+    const hit = cache.get(key);
+    if (hit && hit.expiresAt > now)
+        return hit.promise;
+    const promise = postApi(params);
+    cache.set(key, { expiresAt: now + ttlMs, promise });
+    const evict = () => {
+        if (cache.get(key)?.promise === promise)
+            cache.delete(key);
+    };
+    promise.then(result => {
+        if (result && typeof result === "object" && result.error)
+            evict();
+    }, evict);
+    evictIfNeeded(now);
+    return promise;
+}

package/dist/telemetry/tracingProxy.js

@@ -36,6 +36,10 @@ async function attachSessionIdentity(span, extra) {
             span.setAttribute("enduser.id", identity.userId);
         if (identity?.orgUuid)
             span.setAttribute("mcp.org.uuid", identity.orgUuid);
+        // "SUPPORT" for support-authority sessions (enduser.id is then the
+        // authorityUuid, or the fixed "support-session" marker).
+        if (identity?.sessionType)
+            span.setAttribute("mcp.session.type", identity.sessionType);
     }
     catch (error) {
         logger.debug(`tracing: attachSessionIdentity failed: ${String(error)}`);

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

@@ -3,11 +3,13 @@ import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/entity-lookup-tool-types.js";
 import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "entity-lookup-tool";
 const TOOL_DESCRIPTION = `
-Retrieves specific entities (or devices) by their UUIDs.
-Takes a list of device UUIDs and returns the device information for those specific devices. 
-Use this tool when the user asks for details on devices' states and details about their licenses and features.
+Retrieves specific entities (or devices) by their UUIDs, including license and feature details.
+Use this tool ONLY when you already have exact device UUIDs (e.g. from get-entity-tool, get-org-information, or an earlier tool result).
+
+To look up a device by NAME, do NOT use this tool — use get-entity-tool with a filterBy name predicate instead. NEVER invent or guess placeholder UUIDs; an unknown UUID matches nothing and returns empty results.
+
+Pass deviceUuids: null to return ALL entities of every type (no UUID filter) and narrow with filterBy/includeFields — note that license/feature details are only included when explicit UUIDs are provided.
 The return structure is a JSON object that contains the states of the requested entities.
-This data is exact. Only devices with matching UUIDs will be returned.
 `;
 const TOOL_HANDLER = async (args, extra) => {
     const { deviceUuids, timeZone, tempUnit } = args;
@@ -29,8 +31,10 @@ const TOOL_HANDLER = async (args, extra) => {
 };
 export function createTool(server) {
     server.registerTool(TOOL_NAME, {
+        title: "Entity Lookup",
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS,
         outputSchema: OUTPUT_SCHEMA.shape,
+        annotations: { readOnlyHint: true },
     }, TOOL_HANDLER);
 }

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

@@ -1,21 +1,39 @@
 import { getAccessControlledDoors, getAudioGateways, getBadgeReaders, getButtons, getCameraList, getDoorbellCameras, getDoorSensors, getEnvironmentalGateways, getEnvironmentalSensors, getKeypads, getMotionSensors, } from "../api/get-entity-tool-api.js";
 import DeviceType from "../types/deviceType.js";
-import { TOOL_ARGS } from "../types/get-entity-tool-types.js";
-import { createToolTextContent, extractFromToolExtra } from "../util.js";
+import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/get-entity-tool-types.js";
+import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "get-entity-tool";
 const TOOL_DESCRIPTION = `
 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.
 
 **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\`.
+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. To describe one device in depth (model, firmware, serial, network), pass \`detail: "full"\` together with a \`filterBy\` name predicate so only that device comes back at full size.
+2. **Listing all devices of a type** (cameras, doors, sensors, etc.) for a location or org-wide. The default \`detail: "core"\` keeps lists compact (uuid, name, connection/health status, location, associations).
+3. **Checking device health and connectivity.** Devices with a connection state include a \`connected\` boolean (true = online, false = offline). For "how many devices are offline?" / "which are offline?", pass \`filterBy: [{"field": "connected", "op": "=", "value": false}]\` — the returned list and its \`<type>Count\` sibling then reflect exactly the offline devices, so the count needs no manual tallying. For per-group questions ("per location", "which location has the most offline"), add \`groupBy: "locationUuid"\` to get exact server-computed counts per group — never tally rows yourself.
 
 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.`;
+// Fields kept per device when detail is "core" (the default) — the union of
+// the identifying/health/association fields across every entity type. Fields a
+// type doesn't have are simply absent. "full" skips the projection entirely.
+const CORE_FIELDS = new Set([
+    "uuid",
+    "name",
+    "connectionStatus",
+    "connected",
+    "healthStatus",
+    "healthStatusDetails",
+    "locationUuid",
+    "floorNumber",
+    "temperature",
+    "humidity",
+    "batteryStatus",
+    "associatedCameras",
+    "policyUuid",
+    "remoteUnlockEnabled",
+    "geofenceEnabled",
+]);
 const TOOL_HANDLER = async (args, extra) => {
-    const { entityTypes, timeZone, tempUnit } = args;
-    const filterBy = args.filterBy ?? { locationUuids: null };
-    const locationFilter = filterBy.locationUuids;
+    const { entityTypes, timeZone, tempUnit, detail } = args;
     const { requestModifiers, sessionId } = extractFromToolExtra(extra);
     const promises = [];
     if (entityTypes.includes(DeviceType.CAMERA)) {
@@ -59,17 +77,18 @@ const TOOL_HANDLER = async (args, extra) => {
         for (const key of Object.keys(response)) {
             const value = response[key];
             if (Array.isArray(value)) {
-                // then filter
-                response[key] = value.filter((item) => {
-                    let pass = true;
-                    if (item.locationUuid &&
-                        locationFilter &&
-                        locationFilter.length > 0) {
-                        pass = pass && locationFilter.includes(item.locationUuid);
-                    }
-                    return pass;
-                });
-                response[`${key}Count`] = response[key].length;
+                // The upstream states only carry a 4-color connectionStatus
+                // (RED = disconnected). Derive the uniform `connected` boolean the
+                // description promises so "offline" questions are a filterBy, not a
+                // model-side tally over the raw statuses.
+                let items = value.map((item) => item && typeof item === "object" && "connectionStatus" in item && !("connected" in item)
+                    ? { ...item, connected: item.connectionStatus !== "RED" }
+                    : item);
+                if (detail !== "full") {
+                    items = items.map((item) => Object.fromEntries(Object.entries(item).filter(([field]) => CORE_FIELDS.has(field))));
+                }
+                response[key] = items;
+                response[`${key}Count`] = items.length;
             }
         }
     }
@@ -79,8 +98,14 @@ const TOOL_HANDLER = async (args, extra) => {
             ...curr,
         }), {}),
     };
-    return createToolTextContent(JSON.stringify(ret));
+    return createToolStructuredContent(ret);
 };
 export function createTool(server) {
-    server.tool(TOOL_NAME, TOOL_DESCRIPTION, TOOL_ARGS, TOOL_HANDLER);
+    server.registerTool(TOOL_NAME, {
+        title: "Get Entities",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA.shape,
+        annotations: { readOnlyHint: true },
+    }, TOOL_HANDLER);
 }

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

@@ -1,18 +1,51 @@
+import { z } from "zod";
 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 (_, extra) => {
-    const org = await getOrg(extra._meta?.requestModifiers, extra.sessionId);
+    const response = await getOrg(extra._meta?.requestModifiers, extra.sessionId);
+    if (response?.error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to fetch organization information: ${response.errorMsg ?? response.status ?? "unknown error"}`,
+                },
+            ],
+        };
+    }
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify(org),
+                text: JSON.stringify(response),
             },
         ],
+        structuredContent: response,
     };
 };
 export function createTool(server) {
-    server.tool(TOOL_NAME, TOOL_DESCRIPTION, TOOL_ARGS, TOOL_HANDLER);
+    server.registerTool(TOOL_NAME, {
+        title: "Organization Information",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        // /org/getOrgV2's org record is free-form (contact info, defaults,
+        // settings), so it is declared as an open record rather than enumerated —
+        // field paths like "org.name" / "org.uuid" still project fine.
+        outputSchema: {
+            org: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("The organization record: name, uuid, contact information, camera configuration defaults, org settings. Project with paths like \"org.name\", \"org.uuid\"."),
+            cameraConfigDefaults: z.record(z.string(), z.unknown()).nullable().optional(),
+            cameraConfigOptions: z.record(z.string(), z.unknown()).nullable().optional(),
+            featureFlags: z.record(z.string(), z.string().nullable()).nullable().optional(),
+            error: z.boolean().nullable().optional(),
+            errorMsg: z.string().nullable().optional(),
+            warningMsg: z.string().nullable().optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, TOOL_HANDLER);
 }

package/dist/tools/time-conversion-tool.js

@@ -1,43 +1,71 @@
+import { z } from "zod";
 import { TOOL_ARGS } from "../types/time-conversion-tool-types.js";
 const TOOL_NAME = "time-conversion-tool";
-const TOOL_DESCRIPTION = "This tool is capable of converting to and from epoch and ISO 8601 timestamps. Use this tool when you have one time format and need to convert to the other format. The tool will automatically detect the input format and convert to the other format.";
-const TOOL_HANDLER = async (args, extra) => {
-    const { time_to_convert } = args;
-    if (typeof time_to_convert === "string") {
-        // Input is ISO 8601, convert to epoch
-        const date = new Date(time_to_convert);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({ epoch: date.getTime() }),
-                },
-            ],
-        };
-    }
-    else if (typeof time_to_convert === "number") {
-        // Input is epoch, convert to ISO 8601
-        const date = new Date(time_to_convert);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({ iso: date.toISOString() }),
-                },
-            ],
-        };
-    }
-    else {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({ error: "Invalid input type for time_to_convert" }),
-                },
-            ],
-        };
+const TOOL_DESCRIPTION = `This tool converts between epoch (Unix milliseconds) and ISO 8601 timestamps, auto-detecting the input format: an ISO string returns epoch ms, a number returns the ISO string.
+
+This is the most accurate way to convert timestamps — do NOT convert timestamps yourself.
+
+Accepts a single value or a comma-separated list (results returned in the same order). If a timestamp is timezoned, include the original UTC offset (e.g. '2025-03-05T09:00:00-08:00') rather than converting to UTC yourself.
+
+Example: "2025-03-05T09:00:00-08:00,1741190400000" returns the epoch ms of the first and the ISO string of the second.`;
+/** Convert one trimmed value, auto-detecting ISO vs epoch. */
+function convertOne(value) {
+    // Numbers (or all-digit strings from a comma-separated batch) are epochs.
+    const asNumber = typeof value === "number" ? value : /^-?\d+$/.test(value) ? Number(value) : null;
+    if (asNumber !== null) {
+        const date = new Date(asNumber);
+        if (Number.isNaN(date.getTime()))
+            return { input: value, error: "Invalid epoch timestamp" };
+        return { input: value, iso: date.toISOString() };
     }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return { input: value, error: "Unparseable ISO 8601 timestamp" };
+    return { input: value, epoch: date.getTime() };
+}
+const TOOL_HANDLER = async (args, _extra) => {
+    const { time_to_convert } = args;
+    const values = typeof time_to_convert === "string" && time_to_convert.includes(",")
+        ? time_to_convert.split(",").map((s) => s.trim()).filter((s) => s.length > 0)
+        : [time_to_convert];
+    const results = values.map(convertOne);
+    // Preserve the original single-value shapes ({epoch} / {iso}) for compatibility.
+    const payload = results.length === 1
+        ? results[0].error
+            ? { error: results[0].error }
+            : results[0].epoch !== undefined
+                ? { epoch: results[0].epoch }
+                : { iso: results[0].iso }
+        : { results };
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload),
+            },
+        ],
+        structuredContent: payload,
+    };
 };
+const CONVERSION_RESULT = z.object({
+    input: z.union([z.string(), z.number()]).optional().describe("The value as passed in"),
+    epoch: z.number().optional().describe("Epoch milliseconds (present when the input was ISO)"),
+    iso: z.string().optional().describe("ISO 8601 string (present when the input was an epoch)"),
+    error: z.string().optional().describe("Why this value could not be converted"),
+});
 export function createTool(server) {
-    server.tool(TOOL_NAME, TOOL_DESCRIPTION, TOOL_ARGS, TOOL_HANDLER);
+    server.registerTool(TOOL_NAME, {
+        title: "Time Conversion",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        // Single-value calls keep their legacy flat shapes ({epoch} / {iso} /
+        // {error}); comma-separated batches return {results: [...]}.
+        outputSchema: {
+            epoch: z.number().optional(),
+            iso: z.string().optional(),
+            error: z.string().optional(),
+            results: z.array(CONVERSION_RESULT).optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, TOOL_HANDLER);
 }

package/dist/tools/time-tool.js

@@ -1,13 +1,16 @@
+import { z } from "zod";
 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 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".
+const TOOL_DESCRIPTION = `This tool converts a natural-language description of time ("today", "5 days ago", "last week", "this morning") into concrete timestamps. Use it when you need a timestamp as input to another tool, or when the user explicitly asks for the current time. Keep time_description as close to the user's original phrasing as possible.
 
-**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.
+**Call it at most once per distinct time reference.** The current time does not change during this conversation — once you have retrieved "now"/"today", reuse that result and reason about other relative dates from it. Do NOT call time-tool again for a time reference you already resolved, and do not call it at all for questions that have no time component.
 
-**Default timezone:** Assume "America/Los_Angeles" unless the user specifies otherwise or device/location context indicates a different one.`;
+**Timezone:** Pass the timezone of the relevant device/location when known; otherwise a timezone the user stated; otherwise UTC.`;
 const TOOL_HANDLER = async (args, extra) => {
     const { time_description, timezone } = args;
+    // parseTimeDescription throws on an unparseable description; the SDK turns a
+    // thrown handler error into an isError result, which skips output validation.
     const result = parseTimeDescription(time_description ?? undefined, timezone ?? undefined, extra);
     return {
         content: [
@@ -16,8 +19,19 @@ const TOOL_HANDLER = async (args, extra) => {
                 text: JSON.stringify(result),
             },
         ],
+        structuredContent: result,
     };
 };
 export function createTool(server) {
-    server.tool(TOOL_NAME, TOOL_DESCRIPTION, TOOL_ARGS, TOOL_HANDLER);
+    server.registerTool(TOOL_NAME, {
+        title: "Current Time",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: {
+            timestamp: z.number().optional().describe("Epoch milliseconds of the resolved time"),
+            iso: z.string().nullable().optional().describe("ISO 8601 form of the resolved time"),
+            timezone: z.string().nullable().optional().describe("IANA timezone the time was resolved in"),
+        },
+        annotations: { readOnlyHint: true },
+    }, TOOL_HANDLER);
 }