@dereekb/firebase-server 13.16.0 → 13.18.0

package/mcp/index.esm.js

@@ -15,7 +15,7 @@ function _class_call_check$5(instance, Constructor) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
-function _define_property$7(obj, key, value) {
+function _define_property$9(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -45,6 +45,23 @@ function _define_property$7(obj, key, value) {
  * Default `instructions` string advertised by the MCP server on the JSON-RPC `initialize`
  * handshake. Apps may override this via {@link McpModuleConfig.serverInstructions}.
  */ var DEFAULT_MCP_SERVER_INSTRUCTIONS = 'A set of call-model tools generated automatically.';
+/**
+ * Default name of the auto-injected reason parameter added to every advertised MCP tool's input
+ * schema. See {@link McpReasonParameterConfig.parameterName}.
+ */ var DEFAULT_MCP_REASON_PARAMETER_NAME = 'reason';
+/**
+ * Default maximum length (in characters) of the auto-injected reason parameter. Values longer than
+ * this are clamped server-side before being forwarded to analytics. See
+ * {@link McpReasonParameterConfig.maxLength}.
+ */ var DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH = 250;
+/**
+ * Default required-ness of the auto-injected reason parameter. See
+ * {@link McpReasonParameterConfig.required}.
+ */ var DEFAULT_MCP_REASON_PARAMETER_REQUIRED = true;
+/**
+ * Default description advertised for the auto-injected reason parameter on every tool's input schema.
+ * See {@link McpReasonParameterConfig.description}.
+ */ var DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION = 'A brief human-readable reason (≤250 chars) explaining why this tool is being called. Recorded for analytics/audit only; not part of the operation.';
 /**
  * Configuration for the firebase-server/mcp module.
  *
@@ -69,7 +86,7 @@ function _define_property$7(obj, key, value) {
      * discovery document. Claude custom-connector reads this to discover the OIDC issuer.
      *
      * @example 'https://api.example.com/oidc'
-     */ _define_property$7(this, "oidcIssuer", void 0);
+     */ _define_property$9(this, "oidcIssuer", void 0);
     /**
      * The canonical resource URL of the MCP endpoint.
      *
@@ -77,19 +94,19 @@ function _define_property$7(obj, key, value) {
      * and used as the audience the access token's `aud` claim should match.
      *
      * @example 'https://api.example.com/mcp'
-     */ _define_property$7(this, "mcpUrl", void 0);
+     */ _define_property$9(this, "mcpUrl", void 0);
     /**
      * Optional name advertised on the MCP `initialize` handshake. Defaults to
      * {@link DEFAULT_MCP_SERVER_NAME}.
-     */ _define_property$7(this, "serverName", void 0);
+     */ _define_property$9(this, "serverName", void 0);
     /**
      * Optional version advertised on the MCP `initialize` handshake.
-     */ _define_property$7(this, "serverVersion", void 0);
+     */ _define_property$9(this, "serverVersion", void 0);
     /**
      * Optional override for the `instructions` string passed to `new McpServer(...)` and
      * advertised on the JSON-RPC `initialize` handshake. Defaults to
      * {@link DEFAULT_MCP_SERVER_INSTRUCTIONS}.
-     */ _define_property$7(this, "serverInstructions", void 0);
+     */ _define_property$9(this, "serverInstructions", void 0);
     /**
      * Absolute path to a pre-rendered MCP manifest JSON file produced by
      * `dbx-cli-generate-mcp-manifest`. When set, the runtime reads it once at
@@ -99,7 +116,17 @@ function _define_property$7(obj, key, value) {
      * Optional. When unset or the file is missing, the runtime falls back to
      * today's behavior (auto-generated descriptions, ArkType-derived input
      * schemas, no output schemas) and emits a single boot warning.
-     */ _define_property$7(this, "mcpManifestPath", void 0);
+     */ _define_property$9(this, "mcpManifestPath", void 0);
+    /**
+     * Absolute path to a pre-rendered route manifest JSON file produced by
+     * `dbx-cli-generate-route-manifest`. When set, the runtime reads it once at
+     * boot and registers the built-in `url-models` tool, which decodes an app URL
+     * into the Firestore models its page renders.
+     *
+     * Optional. When unset or the file is missing, the runtime skips registering
+     * `url-models` and emits a single boot warning when the path was set but
+     * unreadable.
+     */ _define_property$9(this, "mcpRouteManifestPath", void 0);
     /**
      * When `true`, the MCP server only advertises tools whose effective read-only classification is `true`.
      *
@@ -109,19 +136,29 @@ function _define_property$7(obj, key, value) {
      *
      * The advertised `serverName` on the JSON-RPC `initialize` handshake is suffixed with
      * ` (read-only)` so the client surface reflects the mode.
-     */ _define_property$7(this, "readOnly", void 0);
+     */ _define_property$9(this, "readOnly", void 0);
+    /**
+     * Controls the auto-injected `reason` parameter added to every advertised tool's input schema.
+     *
+     * Enabled by default (unset / `true` = defaults on). Pass a {@link McpReasonParameterConfig} object
+     * to tune `required`, `maxLength`, `description`, or `parameterName`, or `false` to disable it.
+     *
+     * When enabled, every advertised tool's `inputSchema` carries a required `reason` string the model
+     * fills with a short justification for the call. The value is forwarded to analytics and stripped
+     * from the dispatched handler body. See {@link McpReasonParameterConfig}.
+     */ _define_property$9(this, "reasonParameter", void 0);
 };
 /**
  * NestJS injection token for the optional {@link McpAuthRoleReader} provider.
  */ var MCP_AUTH_ROLE_READER = 'MCP_AUTH_ROLE_READER';
 
-function _type_of$3(obj) {
+function _type_of$5(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
 function __decorate(decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if ((typeof Reflect === "undefined" ? "undefined" : _type_of$3(Reflect)) === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    if ((typeof Reflect === "undefined" ? "undefined" : _type_of$5(Reflect)) === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
@@ -135,6 +172,206 @@ typeof SuppressedError === "function" ? SuppressedError : function(error, suppre
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+function _array_like_to_array$a(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes$7(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$a(arr);
+}
+function _define_property$8(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _iterable_to_array$7(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread$7() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _object_spread$5(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property$8(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys$3(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props$3(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys$3(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
+function _to_consumable_array$7(arr) {
+    return _array_without_holes$7(arr) || _iterable_to_array$7(arr) || _unsupported_iterable_to_array$a(arr) || _non_iterable_spread$7();
+}
+function _type_of$4(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function _unsupported_iterable_to_array$a(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$a(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$a(o, minLen);
+}
+/**
+ * Normalizes the app-supplied {@link McpModuleConfig.reasonParameter} value (object / boolean /
+ * undefined) into a fully-resolved {@link ResolvedMcpReasonParameterConfig} with the package defaults
+ * applied.
+ *
+ * - `undefined` / `true` → defaults, enabled.
+ * - `false` → defaults, but `enabled: false`.
+ * - object → per-field overrides on top of the defaults (`enabled` defaults to `true`).
+ *
+ * @param config - The raw config from {@link McpModuleConfig.reasonParameter}.
+ * @returns The resolved config with all defaults applied.
+ */ function resolveMcpReasonParameterConfig(config) {
+    var result;
+    if (config === false) {
+        result = {
+            enabled: false,
+            required: DEFAULT_MCP_REASON_PARAMETER_REQUIRED,
+            maxLength: DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH,
+            description: DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION,
+            parameterName: DEFAULT_MCP_REASON_PARAMETER_NAME
+        };
+    } else if (config == null || config === true) {
+        result = {
+            enabled: true,
+            required: DEFAULT_MCP_REASON_PARAMETER_REQUIRED,
+            maxLength: DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH,
+            description: DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION,
+            parameterName: DEFAULT_MCP_REASON_PARAMETER_NAME
+        };
+    } else {
+        var _config_enabled, _config_required, _config_maxLength, _config_description, _config_parameterName;
+        result = {
+            enabled: (_config_enabled = config.enabled) !== null && _config_enabled !== void 0 ? _config_enabled : true,
+            required: (_config_required = config.required) !== null && _config_required !== void 0 ? _config_required : DEFAULT_MCP_REASON_PARAMETER_REQUIRED,
+            maxLength: (_config_maxLength = config.maxLength) !== null && _config_maxLength !== void 0 ? _config_maxLength : DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH,
+            description: (_config_description = config.description) !== null && _config_description !== void 0 ? _config_description : DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION,
+            parameterName: (_config_parameterName = config.parameterName) !== null && _config_parameterName !== void 0 ? _config_parameterName : DEFAULT_MCP_REASON_PARAMETER_NAME
+        };
+    }
+    return result;
+}
+/**
+ * Returns `true` when the JSON schema already declares a property named `name` under `properties`.
+ *
+ * Used as the collision guard so a handler that legitimately consumes its own field of the same name
+ * is never double-declared (schema injection) or stripped (arg extraction).
+ *
+ * @param schema - The candidate JSON schema object (may be `undefined`).
+ * @param name - The property name to look for.
+ * @returns Whether the schema's `properties` already contains `name`.
+ */ function mcpSchemaDeclaresProperty(schema, name) {
+    var properties = schema === null || schema === void 0 ? void 0 : schema.properties;
+    return properties != null && (typeof properties === "undefined" ? "undefined" : _type_of$4(properties)) === 'object' && Object.prototype.hasOwnProperty.call(properties, name);
+}
+/**
+ * Returns a NEW JSON schema object with the reason parameter property merged into `properties` (and
+ * appended to `required` when configured). Never mutates the input — the static wire schemas are
+ * shared module-level constants reused across requests.
+ *
+ * Self-skips (returns the input schema unchanged) when the config is disabled or the schema already
+ * declares the parameter name. Defensive against a non-object / missing-`properties` input.
+ *
+ * @param inputSchema - The tool's resolved input schema.
+ * @param resolved - The resolved reason-parameter config.
+ * @returns A new schema carrying the reason property, or the original schema when skipped.
+ */ function applyMcpReasonParameterToSchema(inputSchema, resolved) {
+    var result = inputSchema;
+    if (resolved.enabled && !mcpSchemaDeclaresProperty(inputSchema, resolved.parameterName)) {
+        var _base_type;
+        var base = (typeof inputSchema === "undefined" ? "undefined" : _type_of$4(inputSchema)) === 'object' && inputSchema != null ? inputSchema : {};
+        var existingProperties = _type_of$4(base.properties) === 'object' && base.properties != null ? base.properties : {};
+        var next = _object_spread_props$3(_object_spread$5({}, base), {
+            type: (_base_type = base.type) !== null && _base_type !== void 0 ? _base_type : 'object',
+            properties: _object_spread_props$3(_object_spread$5({}, existingProperties), _define_property$8({}, resolved.parameterName, {
+                type: 'string',
+                maxLength: resolved.maxLength,
+                description: resolved.description
+            }))
+        });
+        if (resolved.required) {
+            var existingRequired = Array.isArray(base.required) ? base.required : [];
+            next.required = existingRequired.includes(resolved.parameterName) ? _to_consumable_array$7(existingRequired) : _to_consumable_array$7(existingRequired).concat([
+                resolved.parameterName
+            ]);
+        }
+        result = next;
+    }
+    return result;
+}
+/**
+ * Splits the auto-injected reason value out of a tool call's raw arguments.
+ *
+ * When enabled and the tool did NOT declare its own field of the same name: shallow-copies the args,
+ * deletes the parameter key, and coerces + clamps the value to `maxLength` (the client is not trusted).
+ * An empty / absent value yields `reason: undefined`.
+ *
+ * Otherwise (disabled, or the handler legitimately owns the field) returns the args unchanged so a
+ * field the handler actually consumes is never stripped.
+ *
+ * @param args - The raw `tools/call` arguments.
+ * @param resolved - The resolved reason-parameter config.
+ * @param toolDeclaresOwnReason - Whether the tool's own input schema already declares the parameter.
+ * @returns The extracted reason plus the (possibly stripped) args to dispatch.
+ */ function extractMcpReasonFromArgs(args, resolved, toolDeclaresOwnReason) {
+    var result;
+    if (resolved.enabled && !toolDeclaresOwnReason && Object.prototype.hasOwnProperty.call(args, resolved.parameterName)) {
+        var rawValue = args[resolved.parameterName];
+        var nextArgs = _object_spread$5({}, args);
+        delete nextArgs[resolved.parameterName];
+        var stringValue = rawValue == null ? '' : String(rawValue);
+        var clamped = stringValue.length > resolved.maxLength ? stringValue.slice(0, resolved.maxLength) : stringValue;
+        result = {
+            reason: clamped.length > 0 ? clamped : undefined,
+            args: nextArgs
+        };
+    } else {
+        result = {
+            reason: undefined,
+            args: args
+        };
+    }
+    return result;
+}
+
 function _class_call_check$4(instance, Constructor) {
     if (!(instance instanceof Constructor)) {
         throw new TypeError("Cannot call a class as a function");
@@ -190,73 +427,356 @@ function _class_call_check$4(instance, Constructor) {
     return isDefault ? "".concat(modelType, ".").concat(call, "._") : "".concat(modelType, ".").concat(call, ".").concat(specifier);
 }
 
-function asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, key, arg) {
+function _array_like_to_array$9(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_with_holes$5(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function _iterable_to_array_limit$5(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
     try {
-        var info = gen[key](arg);
-        var value = info.value;
-    } catch (error) {
-        reject(error);
-        return;
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
+        }
     }
-    if (info.done) {
-        resolve(value);
+    return _arr;
+}
+function _non_iterable_rest$5() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _sliced_to_array$5(arr, i) {
+    return _array_with_holes$5(arr) || _iterable_to_array_limit$5(arr, i) || _unsupported_iterable_to_array$9(arr, i) || _non_iterable_rest$5();
+}
+function _unsupported_iterable_to_array$9(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$9(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$9(o, minLen);
+}
+/**
+ * Runtime mirror of the build-time route manifest schema + a ported URL matcher.
+ *
+ * Structural mirror of `@dereekb/dbx-cli`'s `route-manifest.ts` types and the
+ * pure `url-match.ts` matcher, so the firebase-server/mcp runtime can consume
+ * the generated `route.manifest.json` without taking a runtime dependency on
+ * the build-time CLI package. Both sides bump {@link ROUTE_MANIFEST_VERSION}
+ * together when the manifest shape changes.
+ */ /**
+ * Version stamp embedded in `route.manifest.json`. Runtime loaders refuse
+ * manifests whose `version` does not match. Mirror in `@dereekb/dbx-cli`'s
+ * `ROUTE_MANIFEST_VERSION` — bump both together.
+ */ var ROUTE_MANIFEST_VERSION = 1;
+/**
+ * Extracts the normalized pathname from a full URL or a bare path. Strips the
+ * scheme/host/port, query string, and hash; collapses an empty path to `/` and
+ * trims a single trailing slash.
+ *
+ * @param url - A full URL (`https://app.example.co/worker/x/timesheets/list`) or bare path.
+ * @returns The normalized pathname.
+ *
+ * @example
+ * ```ts
+ * parseUrlModelsPathname('https://app.hellosubs.co/worker/abc/timesheets/list/'); // => '/worker/abc/timesheets/list'
+ * ```
+ */ function parseUrlModelsPathname(url) {
+    var trimmed = url.trim();
+    var pathname;
+    if (RegExp("^[a-z][a-z0-9+.-]*:\\/\\/", "iu").test(trimmed)) {
+        pathname = new URL(trimmed).pathname;
     } else {
-        Promise.resolve(value).then(_next, _throw);
+        var hashStripped = trimmed.split('#', 1)[0];
+        var pathPart = hashStripped.split('?', 1)[0];
+        pathname = pathPart.startsWith('/') ? pathPart : "/".concat(pathPart);
     }
+    return normalizePathname(pathname);
 }
-function _async_to_generator$5(fn) {
-    return function() {
-        var self = this, args = arguments;
-        return new Promise(function(resolve, reject) {
-            var gen = fn.apply(self, args);
-            function _next(value) {
-                asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, "next", value);
+/**
+ * Matches a URL against the manifest's states, preferring a literal match over
+ * a parameterised one. A tie at either tier collapses to `ambiguous`; otherwise
+ * the closest near-misses are scored and returned in a `none` result.
+ *
+ * @param input - The manifest and the URL (or pathname) to resolve.
+ * @returns A discriminated match / ambiguous / none result.
+ */ function matchRouteManifestUrl(input) {
+    var pathname = parseUrlModelsPathname(input.url);
+    var states = input.manifest.states;
+    var literal = states.filter(function(s) {
+        return s.fullUrl !== undefined && normalizePathname(s.fullUrl) === pathname;
+    });
+    var result;
+    if (literal.length === 1) {
+        result = {
+            kind: 'match',
+            via: 'literal',
+            state: literal[0],
+            params: {},
+            pathname: pathname
+        };
+    } else if (literal.length > 1) {
+        result = {
+            kind: 'ambiguous',
+            states: literal,
+            pathname: pathname
+        };
+    } else {
+        result = matchParamOrNone(states, pathname);
+    }
+    return result;
+}
+function matchParamOrNone(states, pathname) {
+    var inputSegments = splitSegments(pathname);
+    var hits = [];
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = states[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var state = _step.value;
+            if (state.fullUrl === undefined || !hasParamSegment(state.fullUrl)) {
+                continue;
             }
-            function _throw(err) {
-                asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, "throw", err);
+            var params = tryMatchSegments(splitSegments(state.fullUrl), inputSegments);
+            if (params) {
+                hits.push({
+                    state: state,
+                    params: params
+                });
             }
-            _next(undefined);
-        });
-    };
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    var result;
+    if (hits.length === 1) {
+        result = {
+            kind: 'match',
+            via: 'param',
+            state: hits[0].state,
+            params: hits[0].params,
+            pathname: pathname
+        };
+    } else if (hits.length > 1) {
+        result = {
+            kind: 'ambiguous',
+            states: hits.map(function(h) {
+                return h.state;
+            }),
+            pathname: pathname
+        };
+    } else {
+        result = {
+            kind: 'none',
+            candidates: scoreCandidates(states, pathname),
+            pathname: pathname
+        };
+    }
+    return result;
 }
-function _instanceof$1(left, right) {
-    "@swc/helpers - instanceof";
-    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
-        return !!right[Symbol.hasInstance](left);
+// MARK: Pure URL helpers (mirror of @dereekb/dbx-cli url-match.ts)
+function normalizePathname(pathname) {
+    var result;
+    if (pathname.length === 0) {
+        result = '/';
+    } else if (pathname.length > 1 && pathname.endsWith('/')) {
+        result = pathname.slice(0, -1);
     } else {
-        return left instanceof right;
+        result = pathname;
     }
+    return result;
 }
-function _ts_generator$5(thisArg, body) {
-    var f, y, t, _ = {
-        label: 0,
-        sent: function() {
-            if (t[0] & 1) throw t[1];
-            return t[1];
-        },
-        trys: [],
-        ops: []
-    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
-    return d(g, "next", {
-        value: verb(0)
-    }), d(g, "throw", {
-        value: verb(1)
-    }), d(g, "return", {
-        value: verb(2)
-    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
-        value: function() {
-            return this;
-        }
-    }), g;
-    function verb(n) {
-        return function(v) {
-            return step([
-                n,
-                v
-            ]);
-        };
+function splitSegments(path) {
+    var normalized = path.startsWith('/') ? path.slice(1) : path;
+    return normalized.length === 0 ? [] : normalized.split('/');
+}
+function hasParamSegment(path) {
+    return path.includes(':') || path.includes('{');
+}
+function tryMatchSegments(route, input) {
+    if (route.length !== input.length) {
+        return undefined;
     }
-    function step(op) {
+    var params = {};
+    var result = params;
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = route.entries()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var _step_value = _sliced_to_array$5(_step.value, 2), i = _step_value[0], r = _step_value[1];
+            var v = input[i];
+            if (r.startsWith(':')) {
+                params[r.slice(1)] = decodeURIComponent(v);
+            } else if (r.startsWith('{') && r.endsWith('}')) {
+                var inner = r.slice(1, -1);
+                var colonIdx = inner.indexOf(':');
+                var key = colonIdx >= 0 ? inner.slice(0, colonIdx) : inner;
+                params[key] = decodeURIComponent(v);
+            } else if (r !== v) {
+                result = undefined;
+                break;
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return result;
+}
+function scoreCandidates(states, pathname) {
+    var segments = splitSegments(pathname);
+    var scored = [];
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = states[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var state = _step.value;
+            if (state.fullUrl === undefined) {
+                continue;
+            }
+            var candidateSegments = splitSegments(state.fullUrl);
+            var score = 0;
+            var maxIndex = Math.min(segments.length, candidateSegments.length);
+            for(var i = 0; i < maxIndex; i += 1){
+                if (segments[i] === candidateSegments[i]) {
+                    score += 2;
+                } else if (candidateSegments[i].startsWith(':') || candidateSegments[i].startsWith('{')) {
+                    score += 1;
+                } else {
+                    break;
+                }
+            }
+            if (score > 0) {
+                scored.push({
+                    state: state,
+                    score: score
+                });
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    scored.sort(function(a, b) {
+        return b.score - a.score;
+    });
+    return scored.slice(0, 5).map(function(s) {
+        return s.state;
+    });
+}
+
+function asyncGeneratorStep$6(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator$6(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep$6(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep$6(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _instanceof$1(left, right) {
+    "@swc/helpers - instanceof";
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+function _ts_generator$6(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
         if (f) throw new TypeError("Generator is already executing.");
         while(g && (g = 0, op[0] && (_ = 0)), _)try {
             if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
@@ -355,9 +875,9 @@ function _ts_generator$5(thisArg, body) {
  * @param details - The handler-level API details (carries the mapper + Tier 2/3 formatters).
  * @returns The MCP tool response content.
  */ function formatMcpToolResponse(result, params, details) {
-    return _async_to_generator$5(function() {
+    return _async_to_generator$6(function() {
         var mcp, value, _tmp, context, response, summary;
-        return _ts_generator$5(this, function(_state) {
+        return _ts_generator$6(this, function(_state) {
             switch(_state.label){
                 case 0:
                     mcp = details === null || details === void 0 ? void 0 : details.mcp;
@@ -510,6 +1030,28 @@ function stringifyResult(result) {
     }
     return READ_ONLY_BY_CALL_TYPE[callType];
 }
+/**
+ * Maps an effective read-only classification to the standard MCP {@link ToolAnnotations} hints
+ * advertised on `tools/list`.
+ *
+ * A definitively read-only tool advertises `{ readOnlyHint: true }`. Everything else — a known
+ * write (`false`) or an unclassified verb (`undefined`, e.g. `invoke`/custom) — fails safe to
+ * `{ readOnlyHint: false, destructiveHint: true }` so a client never mistakes an ambiguous tool
+ * for a safe read. `idempotentHint` / `openWorldHint` are intentionally left unset.
+ *
+ * Co-located with {@link resolveEffectiveReadOnly} / {@link READ_ONLY_BY_CALL_TYPE} so the
+ * read/write classification rules stay in one file.
+ *
+ * @param effectiveReadOnly - The resolved read-only classification from {@link resolveEffectiveReadOnly}.
+ * @returns The MCP annotations describing the tool's read/write behaviour.
+ */ function resolveMcpToolAnnotations(effectiveReadOnly) {
+    return effectiveReadOnly === true ? {
+        readOnlyHint: true
+    } : {
+        readOnlyHint: false,
+        destructiveHint: true
+    };
+}
 /**
  * Resolves the OIDC scope required to invoke a given call type, or `undefined` for
  * non-CRUD calls. Thin re-export so the tool generator doesn't need to reach into
@@ -521,15 +1063,15 @@ function stringifyResult(result) {
     return callModelOidcScopeForCallType(callType);
 }
 
-function _array_like_to_array$7(arr, len) {
+function _array_like_to_array$8(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_with_holes$3(arr) {
+function _array_with_holes$4(arr) {
     if (Array.isArray(arr)) return arr;
 }
-function _iterable_to_array_limit$3(arr, i) {
+function _iterable_to_array_limit$4(arr, i) {
     var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
     if (_i == null) return;
     var _arr = [];
@@ -553,23 +1095,23 @@ function _iterable_to_array_limit$3(arr, i) {
     }
     return _arr;
 }
-function _non_iterable_rest$3() {
+function _non_iterable_rest$4() {
     throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _sliced_to_array$3(arr, i) {
-    return _array_with_holes$3(arr) || _iterable_to_array_limit$3(arr, i) || _unsupported_iterable_to_array$7(arr, i) || _non_iterable_rest$3();
+function _sliced_to_array$4(arr, i) {
+    return _array_with_holes$4(arr) || _iterable_to_array_limit$4(arr, i) || _unsupported_iterable_to_array$8(arr, i) || _non_iterable_rest$4();
 }
-function _type_of$2(obj) {
+function _type_of$3(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
-function _unsupported_iterable_to_array$7(o, minLen) {
+function _unsupported_iterable_to_array$8(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$7(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$8(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$7(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$8(o, minLen);
 }
 /**
  * Default `toJsonSchema()` options.
@@ -605,18 +1147,73 @@ function _unsupported_iterable_to_array$7(o, minLen) {
     var inputSchema = (_input_inputSchema = input.inputSchema) !== null && _input_inputSchema !== void 0 ? _input_inputSchema : {
         type: 'object'
     };
-    var entry = input.outputSchema == null ? {
+    var entry = {
         name: input.name,
         description: input.description,
         inputSchema: inputSchema
-    } : {
-        name: input.name,
-        description: input.description,
-        inputSchema: inputSchema,
-        outputSchema: input.outputSchema
     };
+    if (input.outputSchema != null) {
+        entry.outputSchema = input.outputSchema;
+    }
+    if (input.annotations != null) {
+        entry.annotations = input.annotations;
+    }
     return Object.freeze(entry);
 }
+/**
+ * Description prefix prepended to a mutating tool's description so MCP clients that don't render
+ * {@link ToolAnnotations} still surface the write signal in plain text.
+ */ var MCP_WRITE_TOOL_DESCRIPTION_PREFIX = '[WRITE] ';
+/**
+ * Prepends {@link MCP_WRITE_TOOL_DESCRIPTION_PREFIX} to a description when its annotations mark the
+ * tool as a write (`readOnlyHint === false`). Read-only tools are returned unchanged.
+ *
+ * @param description - The base tool description.
+ * @param annotations - The resolved MCP annotations for the tool.
+ * @returns The description, prefixed with the write marker when the tool mutates.
+ */ function applyWriteMarker(description, annotations) {
+    return annotations.readOnlyHint === false ? "".concat(MCP_WRITE_TOOL_DESCRIPTION_PREFIX).concat(description) : description;
+}
+/**
+ * Assembles a statically-registered {@link McpToolDefinition} with consistent MCP annotations.
+ *
+ * Built-in tools (e.g. `whoami`, `model-get`, `batch-execute`) don't flow through
+ * {@link buildToolFromCandidate}, so this is their analogous single source of truth: it derives the
+ * read/write annotations from {@link BuildStaticToolDefinitionInput.effectiveReadOnly} via
+ * {@link resolveMcpToolAnnotations}, applies the {@link MCP_WRITE_TOOL_DESCRIPTION_PREFIX} write
+ * marker to the description, then mirrors the annotations onto both the definition's `annotations`
+ * field and the frozen {@link McpToolDefinition.staticWireEntry}. Centralizing this guarantees no
+ * built-in tool reaches `tools/list` un-annotated (which would surface as an uncategorized "other"
+ * tool in clients that bucket by `readOnlyHint`).
+ *
+ * @param input - The tool identity, schemas, dispatch target, static handler, and read-only classification.
+ * @returns A statically-registered {@link McpToolDefinition} to append to the MCP server factory's tool registry.
+ */ function buildStaticToolDefinition(input) {
+    var name = input.name, inputSchema = input.inputSchema, outputSchema = input.outputSchema, dispatch = input.dispatch, staticHandler = input.staticHandler, effectiveReadOnly = input.effectiveReadOnly, rule = input.rule;
+    var annotations = resolveMcpToolAnnotations(effectiveReadOnly);
+    var description = applyWriteMarker(input.description, annotations);
+    return {
+        name: name,
+        description: description,
+        inputSchema: inputSchema,
+        outputSchema: outputSchema,
+        annotations: annotations,
+        dispatch: dispatch,
+        staticHandler: staticHandler,
+        filterMetadata: {
+            visibilityKind: 'declarative',
+            rule: rule !== null && rule !== void 0 ? rule : {},
+            effectiveReadOnly: effectiveReadOnly
+        },
+        staticWireEntry: buildStaticWireEntry({
+            name: name,
+            description: description,
+            inputSchema: inputSchema,
+            outputSchema: outputSchema,
+            annotations: annotations
+        })
+    };
+}
 // MARK: Naming
 /**
  * The default specifier key used when a handler is not behind a specifier router.
@@ -835,18 +1432,18 @@ function _unsupported_iterable_to_array$7(o, minLen) {
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
         for(var _iterator = Object.entries(apiDetails.models)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var _step_value = _sliced_to_array$3(_step.value, 2), modelType = _step_value[0], modelEntry = _step_value[1];
+            var _step_value = _sliced_to_array$4(_step.value, 2), modelType = _step_value[0], modelEntry = _step_value[1];
             var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
             try {
                 for(var _iterator1 = Object.entries(modelEntry.calls)[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
-                    var _step_value1 = _sliced_to_array$3(_step1.value, 2), callType = _step_value1[0], callDetails = _step_value1[1];
+                    var _step_value1 = _sliced_to_array$4(_step1.value, 2), callType = _step_value1[0], callDetails = _step_value1[1];
                     if (callDetails == null) {
                         continue;
                     }
                     var _iteratorNormalCompletion2 = true, _didIteratorError2 = false, _iteratorError2 = undefined;
                     try {
                         for(var _iterator2 = Object.entries(callDetails.specifiers)[Symbol.iterator](), _step2; !(_iteratorNormalCompletion2 = (_step2 = _iterator2.next()).done); _iteratorNormalCompletion2 = true){
-                            var _step_value2 = _sliced_to_array$3(_step2.value, 2), specifierKey = _step_value2[0], handlerDetails = _step_value2[1];
+                            var _step_value2 = _sliced_to_array$4(_step2.value, 2), specifierKey = _step_value2[0], handlerDetails = _step_value2[1];
                             var _ref;
                             var _naming_modelSegments, _handlerDetails_mcp, _handlerDetails_mcp1;
                             if (handlerDetails == null) {
@@ -983,7 +1580,7 @@ function _unsupported_iterable_to_array$7(o, minLen) {
         return;
     }
     var manifestEntry = manifest === null || manifest === void 0 ? void 0 : manifest.get(mcpManifestKey(modelType, callType, specifier));
-    var description = (_ref = manifestEntry === null || manifestEntry === void 0 ? void 0 : manifestEntry.description) !== null && _ref !== void 0 ? _ref : buildDefaultMcpToolDescription(modelType, callType, specifier);
+    var baseDescription = (_ref = manifestEntry === null || manifestEntry === void 0 ? void 0 : manifestEntry.description) !== null && _ref !== void 0 ? _ref : buildDefaultMcpToolDescription(modelType, callType, specifier);
     var inputSchema = resolveInputSchema({
         handlerDetails: handlerDetails,
         manifestEntry: manifestEntry,
@@ -1017,6 +1614,8 @@ function _unsupported_iterable_to_array$7(o, minLen) {
     }
     var requiredScope = (_resolveRequiredScope = resolveRequiredScope(callType)) !== null && _resolveRequiredScope !== void 0 ? _resolveRequiredScope : undefined;
     var effectiveReadOnly = resolveEffectiveReadOnly((_handlerDetails_mcp = handlerDetails.mcp) === null || _handlerDetails_mcp === void 0 ? void 0 : _handlerDetails_mcp.readOnly, callType);
+    var annotations = resolveMcpToolAnnotations(effectiveReadOnly);
+    var description = applyWriteMarker(baseDescription, annotations);
     var filterMetadata;
     if (classified.visibilityKind === 'declarative') {
         filterMetadata = {
@@ -1059,13 +1658,15 @@ function _unsupported_iterable_to_array$7(o, minLen) {
         name: name,
         description: description,
         inputSchema: inputSchema,
-        outputSchema: outputSchema
+        outputSchema: outputSchema,
+        annotations: annotations
     });
     var definition = {
         name: name,
         description: description,
         inputSchema: inputSchema,
         outputSchema: outputSchema,
+        annotations: annotations,
         details: handlerDetails,
         dispatch: dispatch,
         filterMetadata: filterMetadata,
@@ -1094,7 +1695,7 @@ function resolveInputSchema(context) {
     var result;
     try {
         var exported = arktypeToJsonSchemaForExport(handlerDetails.inputType);
-        if (exported && (typeof exported === "undefined" ? "undefined" : _type_of$2(exported)) === 'object') {
+        if (exported && (typeof exported === "undefined" ? "undefined" : _type_of$3(exported)) === 'object') {
             result = exported;
         } else {
             // arktypeToJsonSchemaForExport returned a non-object (shouldn't happen for object schemas).
@@ -1113,15 +1714,15 @@ function resolveInputSchema(context) {
     return result;
 }
 
-function _array_like_to_array$6(arr, len) {
+function _array_like_to_array$7(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_without_holes$5(arr) {
-    if (Array.isArray(arr)) return _array_like_to_array$6(arr);
+function _array_without_holes$6(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$7(arr);
 }
-function asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, key, arg) {
+function asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, key, arg) {
     try {
         var info = gen[key](arg);
         var value = info.value;
@@ -1135,39 +1736,39 @@ function asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, key, arg) {
         Promise.resolve(value).then(_next, _throw);
     }
 }
-function _async_to_generator$4(fn) {
+function _async_to_generator$5(fn) {
     return function() {
         var self = this, args = arguments;
         return new Promise(function(resolve, reject) {
             var gen = fn.apply(self, args);
             function _next(value) {
-                asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, "next", value);
+                asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, "next", value);
             }
             function _throw(err) {
-                asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, "throw", err);
+                asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, "throw", err);
             }
             _next(undefined);
         });
     };
 }
-function _iterable_to_array$5(iter) {
+function _iterable_to_array$6(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
-function _non_iterable_spread$5() {
+function _non_iterable_spread$6() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _to_consumable_array$5(arr) {
-    return _array_without_holes$5(arr) || _iterable_to_array$5(arr) || _unsupported_iterable_to_array$6(arr) || _non_iterable_spread$5();
+function _to_consumable_array$6(arr) {
+    return _array_without_holes$6(arr) || _iterable_to_array$6(arr) || _unsupported_iterable_to_array$7(arr) || _non_iterable_spread$6();
 }
-function _unsupported_iterable_to_array$6(o, minLen) {
+function _unsupported_iterable_to_array$7(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$6(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$7(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$6(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$7(o, minLen);
 }
-function _ts_generator$4(thisArg, body) {
+function _ts_generator$5(thisArg, body) {
     var f, y, t, _ = {
         label: 0,
         sent: function() {
@@ -1310,7 +1911,7 @@ function _ts_generator$4(thisArg, body) {
     };
     var name = MODEL_GET_TOOL_NAME;
     var description = 'Fetch one or more Firestore model documents by key or bare id. Values containing `/` are treated as full keys; bare ids are auto-promoted to `<collectionName>/<id>` for root models. Subcollection models require full keys.';
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: MODEL_GET_INPUT_SCHEMA,
@@ -1320,26 +1921,17 @@ function _ts_generator$4(thisArg, body) {
             modelType: MODEL_GET_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: MODEL_GET_INPUT_SCHEMA,
-            outputSchema: MODEL_GET_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function modelGetToolHandler(args, ctx, deps) {
-    return _async_to_generator$4(function() {
+    return _async_to_generator$5(function() {
         var result, input, identity, resolvedKeys, merged, error;
-        return _ts_generator$4(this, function(_state) {
+        return _ts_generator$5(this, function(_state) {
             switch(_state.label){
                 case 0:
                     _state.trys.push([
@@ -1356,7 +1948,7 @@ function modelGetToolHandler(args, ctx, deps) {
                     resolvedKeys = resolveKeys(input.keys, identity);
                     return [
                         4,
-                        readInChunks({
+                        readInChunks$1({
                             modelType: input.modelType,
                             keys: resolvedKeys,
                             auth: ctx.auth,
@@ -1445,10 +2037,10 @@ function resolveKeys(keys, identity) {
     }
     return resolved;
 }
-function readInChunks(input) {
-    return _async_to_generator$4(function() {
+function readInChunks$1(input) {
+    return _async_to_generator$5(function() {
         var modelType, keys, auth, readDocuments, merged, offset, _merged_results, _merged_errors, batch, partial;
-        return _ts_generator$4(this, function(_state) {
+        return _ts_generator$5(this, function(_state) {
             switch(_state.label){
                 case 0:
                     modelType = input.modelType, keys = input.keys, auth = input.auth, readDocuments = input.readDocuments;
@@ -1470,8 +2062,8 @@ function readInChunks(input) {
                     ];
                 case 2:
                     partial = _state.sent();
-                    (_merged_results = merged.results).push.apply(_merged_results, _to_consumable_array$5(partial.results));
-                    (_merged_errors = merged.errors).push.apply(_merged_errors, _to_consumable_array$5(partial.errors));
+                    (_merged_results = merged.results).push.apply(_merged_results, _to_consumable_array$6(partial.results));
+                    (_merged_errors = merged.errors).push.apply(_merged_errors, _to_consumable_array$6(partial.errors));
                     _state.label = 3;
                 case 3:
                     offset += MCP_MODEL_GET_BATCH_SIZE;
@@ -1562,15 +2154,15 @@ var MODEL_GET_OUTPUT_SCHEMA = {
     }
 };
 
-function _array_like_to_array$5(arr, len) {
+function _array_like_to_array$6(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_without_holes$4(arr) {
-    if (Array.isArray(arr)) return _array_like_to_array$5(arr);
+function _array_without_holes$5(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$6(arr);
 }
-function _define_property$6(obj, key, value) {
+function _define_property$7(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -1583,13 +2175,13 @@ function _define_property$6(obj, key, value) {
     }
     return obj;
 }
-function _iterable_to_array$4(iter) {
+function _iterable_to_array$5(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
-function _non_iterable_spread$4() {
+function _non_iterable_spread$5() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _object_spread$2(target) {
+function _object_spread$4(target) {
     for(var i = 1; i < arguments.length; i++){
         var source = arguments[i] != null ? arguments[i] : {};
         var ownKeys = Object.keys(source);
@@ -1599,12 +2191,12 @@ function _object_spread$2(target) {
             }));
         }
         ownKeys.forEach(function(key) {
-            _define_property$6(target, key, source[key]);
+            _define_property$7(target, key, source[key]);
         });
     }
     return target;
 }
-function ownKeys(object, enumerableOnly) {
+function ownKeys$2(object, enumerableOnly) {
     var keys = Object.keys(object);
     if (Object.getOwnPropertySymbols) {
         var symbols = Object.getOwnPropertySymbols(object);
@@ -1612,27 +2204,27 @@ function ownKeys(object, enumerableOnly) {
     }
     return keys;
 }
-function _object_spread_props(target, source) {
+function _object_spread_props$2(target, source) {
     source = source != null ? source : {};
     if (Object.getOwnPropertyDescriptors) {
         Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
     } else {
-        ownKeys(Object(source)).forEach(function(key) {
+        ownKeys$2(Object(source)).forEach(function(key) {
             Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
         });
     }
     return target;
 }
-function _to_consumable_array$4(arr) {
-    return _array_without_holes$4(arr) || _iterable_to_array$4(arr) || _unsupported_iterable_to_array$5(arr) || _non_iterable_spread$4();
+function _to_consumable_array$5(arr) {
+    return _array_without_holes$5(arr) || _iterable_to_array$5(arr) || _unsupported_iterable_to_array$6(arr) || _non_iterable_spread$5();
 }
-function _unsupported_iterable_to_array$5(o, minLen) {
+function _unsupported_iterable_to_array$6(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$5(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$6(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$5(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$6(o, minLen);
 }
 // MARK: Constants
 /**
@@ -1681,7 +2273,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
     var name = MODEL_INFO_TOOL_NAME;
     var count = deps.manifest.length;
     var description = "Browse the Firestore model catalog (".concat(count, " model").concat(count === 1 ? '' : 's', "). No args returns model groups + counts (start here). ") + '`model` (a modelType/identityConst/collectionPrefix string, or an array of them) returns full detail per match — misses are reported in `notFound`. ' + '`modelGroup` returns the summary list for that group. `all:true` returns the full catalog summary. ' + '`fields` (boolean) forces or suppresses persisted-field detail in list/multiple modes.';
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: MODEL_INFO_INPUT_SCHEMA,
@@ -1691,27 +2283,19 @@ function _unsupported_iterable_to_array$5(o, minLen) {
             modelType: MODEL_INFO_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: MODEL_INFO_INPUT_SCHEMA,
-            outputSchema: MODEL_INFO_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function modelInfoToolHandler(args, _ctx, deps) {
     var result;
     try {
         var input = parseModelInfoInput(args);
-        var output = resolveModelInfoOutput(input, deps.manifest);
+        var resolved = resolveModelInfoOutput(input, deps.manifest);
+        var output = attachReferencedEnums(resolved, deps.enums);
         result = {
             content: [
                 {
@@ -1748,16 +2332,123 @@ function resolveModelInfoOutput(input, manifest) {
     }
     return output;
 }
-// MARK: Input parsing
-function parseModelInfoInput(args) {
-    var modelQueries = parseModelArg(args['model']);
-    var modelGroup = parseModelGroupArg(args['modelGroup']);
-    var all = parseBooleanArg(args['all'], 'all');
-    var fields = parseBooleanArg(args['fields'], 'fields');
-    return _object_spread$2(_object_spread_props(_object_spread$2(_object_spread_props(_object_spread$2({}, modelQueries == null ? {} : {
-        modelQueries: modelQueries
-    }), {
-        modelIsArray: Array.isArray(args['model'])
+// MARK: Enum attachment
+/**
+ * Attaches the value→label tables for every enum referenced (by `enumRef`) on the returned models'
+ * fields — recursively through `nestedFields` — as a top-level `enums` section.
+ *
+ * Gated behind full field detail: only `single` / `multiple` rows and `list` rows that opted into
+ * `fields:true` carry the persisted `fields` array, so the compact default modes are untouched.
+ * Returns the input unchanged when no enum map is wired or no referenced enum resolves.
+ *
+ * @param output - The resolved model-info output.
+ * @param enums - The optional enum value tables keyed by name.
+ * @returns The output, with an `enums` section attached when detailed rows reference known enums.
+ */ function attachReferencedEnums(output, enums) {
+    var result = output;
+    if (enums != null) {
+        var referenced = new Set();
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = collectDetailedEntries(output)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var entry = _step.value;
+                collectFieldEnumRefs(entry.fields, referenced);
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+        var tables = [];
+        var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
+        try {
+            for(var _iterator1 = referenced[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
+                var name = _step1.value;
+                var table = enums[name];
+                if (table != null) tables.push(table);
+            }
+        } catch (err) {
+            _didIteratorError1 = true;
+            _iteratorError1 = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
+                    _iterator1.return();
+                }
+            } finally{
+                if (_didIteratorError1) {
+                    throw _iteratorError1;
+                }
+            }
+        }
+        if (tables.length > 0) {
+            result = _object_spread_props$2(_object_spread$4({}, output), {
+                enums: tables
+            });
+        }
+    }
+    return result;
+}
+/**
+ * Collects the full {@link McpManifestModelEntry} rows (those carrying a persisted `fields` array)
+ * from a model-info output. Summary rows (which expose `fieldCount`, not `fields`) are skipped.
+ *
+ * @param output - The resolved model-info output.
+ * @returns The detailed model entries present in the output.
+ */ function collectDetailedEntries(output) {
+    var rows = [];
+    if (output.mode === 'single') {
+        rows.push(output.model);
+    } else if (output.mode === 'list' || output.mode === 'multiple') {
+        var _rows;
+        (_rows = rows).push.apply(_rows, _to_consumable_array$5(output.models));
+    }
+    return rows.filter(function(row) {
+        return Array.isArray(row.fields);
+    });
+}
+function collectFieldEnumRefs(fields, into) {
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = fields[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var field = _step.value;
+            if (field.enumRef) into.add(field.enumRef);
+            if (field.nestedFields) collectFieldEnumRefs(field.nestedFields, into);
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+}
+// MARK: Input parsing
+function parseModelInfoInput(args) {
+    var modelQueries = parseModelArg(args['model']);
+    var modelGroup = parseModelGroupArg(args['modelGroup']);
+    var all = parseBooleanArg(args['all'], 'all');
+    var fields = parseBooleanArg(args['fields'], 'fields');
+    return _object_spread$4(_object_spread_props$2(_object_spread$4(_object_spread_props$2(_object_spread$4({}, modelQueries == null ? {} : {
+        modelQueries: modelQueries
+    }), {
+        modelIsArray: Array.isArray(args['model'])
     }), modelGroup == null ? {} : {
         modelGroup: modelGroup
     }), {
@@ -1772,14 +2463,14 @@ function parseModelArg(raw) {
         result = undefined;
     } else if (typeof raw === 'string') {
         result = [
-            requireNonEmptyString(raw, 'model')
+            requireNonEmptyString$1(raw, 'model')
         ];
     } else if (Array.isArray(raw)) {
         if (raw.length === 0) {
             throw new Error('model-info: "model" array must contain at least one entry.');
         }
         result = raw.map(function(value, index) {
-            return requireNonEmptyString(value, "model[".concat(index, "]"));
+            return requireNonEmptyString$1(value, "model[".concat(index, "]"));
         });
     } else {
         throw new TypeError('model-info: "model" must be a string or an array of strings when provided.');
@@ -1791,7 +2482,7 @@ function parseModelGroupArg(raw) {
     if (raw == null) {
         result = undefined;
     } else if (typeof raw === 'string') {
-        result = requireNonEmptyString(raw, 'modelGroup');
+        result = requireNonEmptyString$1(raw, 'modelGroup');
     } else {
         throw new TypeError('model-info: "modelGroup" must be a string when provided.');
     }
@@ -1808,7 +2499,7 @@ function parseBooleanArg(raw, label) {
     }
     return result;
 }
-function requireNonEmptyString(value, label) {
+function requireNonEmptyString$1(value, label) {
     if (typeof value !== 'string') {
         throw new TypeError('model-info: "'.concat(label, '" must be a string.'));
     }
@@ -1917,7 +2608,7 @@ function toModelRow(entry, detailed) {
     return detailed ? entry : toSummaryRow(entry);
 }
 function toSummaryRow(entry) {
-    return _object_spread$2({
+    return _object_spread$4({
         modelType: entry.modelType,
         modelName: entry.modelName,
         identityConst: entry.identityConst,
@@ -1945,7 +2636,7 @@ function toSummaryRow(entry) {
  *
  * @__NO_SIDE_EFFECTS__
  */ function computeGroupCounts(manifest) {
-    var grouped = makeValuesGroupMap(_to_consumable_array$4(manifest), function(entry) {
+    var grouped = makeValuesGroupMap(_to_consumable_array$5(manifest), function(entry) {
         var _entry_modelGroup;
         return (_entry_modelGroup = entry.modelGroup) !== null && _entry_modelGroup !== void 0 ? _entry_modelGroup : MODEL_INFO_UNGROUPED_LABEL;
     });
@@ -2155,6 +2846,48 @@ var MODEL_ROW_SCHEMA = {
         }
     }
 };
+/**
+ * JSON-schema for one enum value→label table. Shared with the `enum-info` tool so both advertise the
+ * identical enum shape.
+ */ var ENUM_TABLE_SCHEMA = {
+    type: 'object',
+    required: [
+        'name',
+        'values'
+    ],
+    properties: {
+        name: {
+            type: 'string'
+        },
+        description: {
+            type: 'string'
+        },
+        values: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: [
+                    'name',
+                    'value'
+                ],
+                properties: {
+                    name: {
+                        type: 'string'
+                    },
+                    value: {
+                        type: [
+                            'string',
+                            'number'
+                        ]
+                    },
+                    description: {
+                        type: 'string'
+                    }
+                }
+            }
+        }
+    }
+};
 // MCP's `tools/list` validator requires `outputSchema.type === 'object'` at the root
 // (see @modelcontextprotocol/sdk Zod schema), so the variants are expressed via a top-level
 // object whose nested `oneOf` discriminates by the `mode` literal.
@@ -2210,7 +2943,7 @@ var MODEL_INFO_OUTPUT_SCHEMA = {
             type: 'string',
             description: 'Present when `mode` is `"list"` from a `modelGroup` filter. The canonical group name.'
         },
-        model: _object_spread_props(_object_spread$2({}, MODEL_ROW_SCHEMA), {
+        model: _object_spread_props$2(_object_spread$4({}, MODEL_ROW_SCHEMA), {
             description: 'Present when `mode` is `"single"`. The matched model entry (full detail unless `fields:false`).'
         }),
         notFound: {
@@ -2231,6 +2964,11 @@ var MODEL_INFO_OUTPUT_SCHEMA = {
                     }
                 }
             }
+        },
+        enums: {
+            type: 'array',
+            description: 'Value→label tables for the enums referenced by the returned models’ fields. Present only when full field detail is returned (single/multiple modes, or list/all with `fields:true`) and at least one referenced enum is registered.',
+            items: ENUM_TABLE_SCHEMA
         }
     },
     oneOf: [
@@ -2278,7 +3016,7 @@ var MODEL_INFO_OUTPUT_SCHEMA = {
     ]
 };
 
-function _define_property$5(obj, key, value) {
+function _define_property$6(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -2291,7 +3029,7 @@ function _define_property$5(obj, key, value) {
     }
     return obj;
 }
-function _object_spread$1(target) {
+function _object_spread$3(target) {
     for(var i = 1; i < arguments.length; i++){
         var source = arguments[i] != null ? arguments[i] : {};
         var ownKeys = Object.keys(source);
@@ -2301,7 +3039,7 @@ function _object_spread$1(target) {
             }));
         }
         ownKeys.forEach(function(key) {
-            _define_property$5(target, key, source[key]);
+            _define_property$6(target, key, source[key]);
         });
     }
     return target;
@@ -2340,7 +3078,7 @@ function _object_spread$1(target) {
     };
     var name = MODEL_DECODE_TOOL_NAME;
     var description = 'Decode a Firestore model key ("prefix/id", or subcollection path "parentPrefix/parentId/childPrefix/childId") into { leaf, ancestors, unresolvedPrefixes } using the registered manifest ('.concat(deps.manifest.length, " model").concat(deps.manifest.length === 1 ? '' : 's', ").");
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: MODEL_DECODE_INPUT_SCHEMA,
@@ -2350,20 +3088,11 @@ function _object_spread$1(target) {
             modelType: MODEL_DECODE_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: MODEL_DECODE_INPUT_SCHEMA,
-            outputSchema: MODEL_DECODE_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function modelDecodeToolHandler(args, _ctx, deps) {
@@ -2439,7 +3168,7 @@ function parseModelDecodeInput(args) {
     };
 }
 function toSegment(prefix, id, entry) {
-    var segment = entry ? _object_spread$1({
+    var segment = entry ? _object_spread$3({
         prefix: prefix,
         id: id,
         modelType: entry.modelType,
@@ -2537,18 +3266,210 @@ var MODEL_DECODE_OUTPUT_SCHEMA = {
     }
 };
 
-function _array_like_to_array$4(arr, len) {
+// MARK: Constants
+/**
+ * Reserved tool name for the built-in `enum-info` static tool.
+ */ var ENUM_INFO_TOOL_NAME = 'enum-info';
+/**
+ * Synthetic call type used in the tool's dispatch identity. Mirrors the `info` call shared with
+ * `model-info`.
+ */ var ENUM_INFO_DISPATCH_CALL = 'info';
+/**
+ * Synthetic model type used in the tool's dispatch identity. Apps avoiding collisions should not
+ * register a real model literally named "enum".
+ */ var ENUM_INFO_DISPATCH_MODEL_TYPE = 'enum';
+// MARK: Factory
+/**
+ * Builds the built-in `enum-info` MCP tool definition — the symmetric counterpart to `model-info`
+ * for raw enum decoding.
+ *
+ * Resolves each requested enum name against the manifest's `enums` block and returns the matching
+ * value→label tables; misses land in `notFound`. A bare string is treated as a one-element array.
+ *
+ * Output is delivered as both stringified JSON in `content[0].text` and `structuredContent` so MCP
+ * clients can consume either form.
+ *
+ * @param deps - The frozen enum value tables loaded at boot from the MCP manifest JSON.
+ * @returns A statically-registered {@link McpToolDefinition} ready to be appended to the MCP server
+ *   factory's tool registry.
+ */ function createEnumInfoTool(deps) {
+    var handler = function handler(args, ctx) {
+        return Promise.resolve(enumInfoToolHandler(args, ctx, deps));
+    };
+    var name = ENUM_INFO_TOOL_NAME;
+    var count = Object.keys(deps.enums).length;
+    var description = "Look up enum value→label tables by name (".concat(count, " enum").concat(count === 1 ? '' : 's', ' registered). Pass `enum` (a string or array of enum declaration names, e.g. "JobWorkerTimesheetState") to decode the raw persisted integer/string values a model field stores. Misses are reported in `notFound`.');
+    return buildStaticToolDefinition({
+        name: name,
+        description: description,
+        inputSchema: ENUM_INFO_INPUT_SCHEMA,
+        outputSchema: ENUM_INFO_OUTPUT_SCHEMA,
+        dispatch: {
+            call: ENUM_INFO_DISPATCH_CALL,
+            modelType: ENUM_INFO_DISPATCH_MODEL_TYPE
+        },
+        staticHandler: handler,
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
+}
+// MARK: Handler
+function enumInfoToolHandler(args, _ctx, deps) {
+    var result;
+    try {
+        var names = parseEnumInfoInput(args);
+        var output = resolveEnumInfoOutput(names, deps.enums);
+        result = {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(output)
+                }
+            ],
+            structuredContent: output
+        };
+    } catch (error) {
+        result = formatMcpToolErrorResponse(error);
+    }
+    return result;
+}
+/**
+ * Resolves each requested enum name against the registered value tables.
+ *
+ * @param names - The requested enum declaration names.
+ * @param enums - The registered enum value tables keyed by name.
+ * @returns The matched tables, with any unmatched names in `notFound`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */ function resolveEnumInfoOutput(names, enums) {
+    var found = [];
+    var notFound = [];
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = names[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var name = _step.value;
+            var table = enums[name];
+            if (table == null) {
+                notFound.push(name);
+            } else {
+                found.push(table);
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return notFound.length > 0 ? {
+        enums: found,
+        notFound: notFound
+    } : {
+        enums: found
+    };
+}
+// MARK: Input parsing
+function parseEnumInfoInput(args) {
+    var raw = args['enum'];
+    var result;
+    if (raw == null) {
+        throw new Error('enum-info: "enum" is required and must be a string or an array of strings.');
+    } else if (typeof raw === 'string') {
+        result = [
+            requireNonEmptyString(raw, 'enum')
+        ];
+    } else if (Array.isArray(raw)) {
+        if (raw.length === 0) {
+            throw new Error('enum-info: "enum" array must contain at least one entry.');
+        }
+        result = raw.map(function(value, index) {
+            return requireNonEmptyString(value, "enum[".concat(index, "]"));
+        });
+    } else {
+        throw new TypeError('enum-info: "enum" must be a string or an array of strings.');
+    }
+    return result;
+}
+function requireNonEmptyString(value, label) {
+    if (typeof value !== 'string') {
+        throw new TypeError('enum-info: "'.concat(label, '" must be a string.'));
+    }
+    var trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error('enum-info: "'.concat(label, '" must be a non-empty string.'));
+    }
+    return trimmed;
+}
+// MARK: Schemas
+var ENUM_INFO_INPUT_SCHEMA = {
+    type: 'object',
+    required: [
+        'enum'
+    ],
+    properties: {
+        enum: {
+            description: 'One enum name (string) or many (string array), each matched exactly by declaration name (e.g. "JobWorkerTimesheetState"). Misses are reported in `notFound`.',
+            oneOf: [
+                {
+                    type: 'string',
+                    minLength: 1
+                },
+                {
+                    type: 'array',
+                    minItems: 1,
+                    items: {
+                        type: 'string',
+                        minLength: 1
+                    }
+                }
+            ]
+        }
+    },
+    additionalProperties: false
+};
+var ENUM_INFO_OUTPUT_SCHEMA = {
+    type: 'object',
+    required: [
+        'enums'
+    ],
+    properties: {
+        enums: {
+            type: 'array',
+            description: 'The resolved enum value→label tables, in request order.',
+            items: ENUM_TABLE_SCHEMA
+        },
+        notFound: {
+            type: 'array',
+            description: 'Requested enum names that matched no registered enum.',
+            items: {
+                type: 'string'
+            }
+        }
+    }
+};
+
+function _array_like_to_array$5(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_with_holes$2(arr) {
+function _array_with_holes$3(arr) {
     if (Array.isArray(arr)) return arr;
 }
-function _array_without_holes$3(arr) {
-    if (Array.isArray(arr)) return _array_like_to_array$4(arr);
+function _array_without_holes$4(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$5(arr);
 }
-function _define_property$4(obj, key, value) {
+function _define_property$5(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -2561,10 +3482,10 @@ function _define_property$4(obj, key, value) {
     }
     return obj;
 }
-function _iterable_to_array$3(iter) {
+function _iterable_to_array$4(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
-function _iterable_to_array_limit$2(arr, i) {
+function _iterable_to_array_limit$3(arr, i) {
     var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
     if (_i == null) return;
     var _arr = [];
@@ -2588,13 +3509,13 @@ function _iterable_to_array_limit$2(arr, i) {
     }
     return _arr;
 }
-function _non_iterable_rest$2() {
+function _non_iterable_rest$3() {
     throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _non_iterable_spread$3() {
+function _non_iterable_spread$4() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _object_spread(target) {
+function _object_spread$2(target) {
     for(var i = 1; i < arguments.length; i++){
         var source = arguments[i] != null ? arguments[i] : {};
         var ownKeys = Object.keys(source);
@@ -2604,24 +3525,24 @@ function _object_spread(target) {
             }));
         }
         ownKeys.forEach(function(key) {
-            _define_property$4(target, key, source[key]);
+            _define_property$5(target, key, source[key]);
         });
     }
     return target;
 }
-function _sliced_to_array$2(arr, i) {
-    return _array_with_holes$2(arr) || _iterable_to_array_limit$2(arr, i) || _unsupported_iterable_to_array$4(arr, i) || _non_iterable_rest$2();
+function _sliced_to_array$3(arr, i) {
+    return _array_with_holes$3(arr) || _iterable_to_array_limit$3(arr, i) || _unsupported_iterable_to_array$5(arr, i) || _non_iterable_rest$3();
 }
-function _to_consumable_array$3(arr) {
-    return _array_without_holes$3(arr) || _iterable_to_array$3(arr) || _unsupported_iterable_to_array$4(arr) || _non_iterable_spread$3();
+function _to_consumable_array$4(arr) {
+    return _array_without_holes$4(arr) || _iterable_to_array$4(arr) || _unsupported_iterable_to_array$5(arr) || _non_iterable_spread$4();
 }
-function _unsupported_iterable_to_array$4(o, minLen) {
+function _unsupported_iterable_to_array$5(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$4(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$5(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$4(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$5(o, minLen);
 }
 // MARK: Constants
 /**
@@ -2655,7 +3576,7 @@ function _unsupported_iterable_to_array$4(o, minLen) {
     var name = WHOAMI_TOOL_NAME;
     var appLabel = (_ref = (_deps_auth_app = deps.auth.app) === null || _deps_auth_app === void 0 ? void 0 : _deps_auth_app.app) !== null && _ref !== void 0 ? _ref : 'this server';
     var description = "Reports the authenticated caller's uid, raw custom claims, and decoded role set for `".concat(appLabel, "`. Returns `authenticated: false` for anonymous callers. Claim descriptions are drawn from the build-time auth manifest; only keys actually present on the live token are detailed.");
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: WHOAMI_INPUT_SCHEMA,
@@ -2665,18 +3586,9 @@ function _unsupported_iterable_to_array$4(o, minLen) {
             modelType: WHOAMI_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {},
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: WHOAMI_INPUT_SCHEMA,
-            outputSchema: WHOAMI_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {}
+    });
 }
 // MARK: Handler
 function whoamiToolHandler(ctx, deps) {
@@ -2695,14 +3607,14 @@ function whoamiToolHandler(ctx, deps) {
     }
     var token = (_auth_token = auth.token) !== null && _auth_token !== void 0 ? _auth_token : {};
     var presentKeys = Object.entries(token).filter(function(param) {
-        var _param = _sliced_to_array$2(param, 2), value = _param[1];
+        var _param = _sliced_to_array$3(param, 2), value = _param[1];
         return value !== undefined;
     }).map(function(param) {
-        var _param = _sliced_to_array$2(param, 1), key = _param[0];
+        var _param = _sliced_to_array$3(param, 1), key = _param[0];
         return key;
     });
     var roleSet = deps.roleReader == null ? new Set() : deps.roleReader(token);
-    var roles = _to_consumable_array$3(roleSet).sort(function(a, b) {
+    var roles = _to_consumable_array$4(roleSet).sort(function(a, b) {
         return a.localeCompare(b);
     });
     var claimsByKey = new Map();
@@ -2739,7 +3651,7 @@ function whoamiToolHandler(ctx, deps) {
             if (claim1 == null) {
                 unknownClaimKeys.push(key);
             } else {
-                claimDetails.push(_object_spread({
+                claimDetails.push(_object_spread$2({
                     key: claim1.key,
                     description: claim1.description,
                     grantedRoles: claim1.mapping.roles,
@@ -2764,10 +3676,10 @@ function whoamiToolHandler(ctx, deps) {
             }
         }
     }
-    var output1 = _object_spread({
+    var output1 = _object_spread$2({
         authenticated: true,
         uid: auth.uid,
-        claims: _object_spread({}, token),
+        claims: _object_spread$2({}, token),
         roles: roles,
         claimDetails: claimDetails,
         unknownClaimKeys: unknownClaimKeys
@@ -2874,99 +3786,989 @@ function appendUnknownClaimLines(lines, unknownClaimKeys) {
             if (!_iteratorNormalCompletion && _iterator.return != null) {
                 _iterator.return();
             }
-        } finally{
-            if (_didIteratorError) {
-                throw _iteratorError;
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+}
+// MARK: Schemas
+var WHOAMI_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {},
+    additionalProperties: false
+};
+var WHOAMI_OUTPUT_SCHEMA = {
+    type: 'object',
+    required: [
+        'authenticated',
+        'claims',
+        'roles',
+        'claimDetails',
+        'unknownClaimKeys'
+    ],
+    description: 'Caller identity, raw token claims, decoded role set, and per-claim descriptions for every key present on the live token.',
+    properties: {
+        authenticated: {
+            type: 'boolean'
+        },
+        uid: {
+            type: 'string'
+        },
+        email: {
+            type: 'string'
+        },
+        emailVerified: {
+            type: 'boolean'
+        },
+        app: {
+            type: 'string'
+        },
+        claims: {
+            type: 'object',
+            additionalProperties: true
+        },
+        roles: {
+            type: 'array',
+            items: {
+                type: 'string'
+            }
+        },
+        claimDetails: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: [
+                    'key',
+                    'description',
+                    'grantedRoles',
+                    'inverse',
+                    'tags'
+                ],
+                properties: {
+                    key: {
+                        type: 'string'
+                    },
+                    interfaceName: {
+                        type: 'string'
+                    },
+                    description: {
+                        type: 'string'
+                    },
+                    grantedRoles: {
+                        type: 'array',
+                        items: {
+                            type: 'string'
+                        }
+                    },
+                    inverse: {
+                        type: 'boolean'
+                    },
+                    tags: {
+                        type: 'array',
+                        items: {
+                            type: 'string'
+                        }
+                    }
+                }
+            }
+        },
+        unknownClaimKeys: {
+            type: 'array',
+            items: {
+                type: 'string'
+            }
+        }
+    }
+};
+
+function _array_like_to_array$4(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_with_holes$2(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function _array_without_holes$3(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$4(arr);
+}
+function asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator$4(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _define_property$4(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _iterable_to_array$3(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _iterable_to_array_limit$2(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
+    try {
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
+        }
+    }
+    return _arr;
+}
+function _non_iterable_rest$2() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _non_iterable_spread$3() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _object_spread$1(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property$4(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys$1(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props$1(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys$1(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
+function _sliced_to_array$2(arr, i) {
+    return _array_with_holes$2(arr) || _iterable_to_array_limit$2(arr, i) || _unsupported_iterable_to_array$4(arr, i) || _non_iterable_rest$2();
+}
+function _to_consumable_array$3(arr) {
+    return _array_without_holes$3(arr) || _iterable_to_array$3(arr) || _unsupported_iterable_to_array$4(arr) || _non_iterable_spread$3();
+}
+function _unsupported_iterable_to_array$4(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$4(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$4(o, minLen);
+}
+function _ts_generator$4(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+// MARK: Constants
+/**
+ * Reserved tool name for the built-in `url-models` static tool.
+ */ var URL_MODELS_TOOL_NAME = 'url-models';
+/**
+ * Synthetic call type used in the tool's dispatch identity.
+ */ var URL_MODELS_DISPATCH_CALL = 'url-models';
+/**
+ * Synthetic model type used in the tool's dispatch identity. The tool isn't
+ * bound to a real model (the `url` is its input), so we use the literal "route".
+ */ var URL_MODELS_DISPATCH_MODEL_TYPE = 'route';
+/**
+ * Placeholder segment standing for the caller's authenticated uid.
+ */ var AUTH_UID_PLACEHOLDER = '{authUid}';
+// MARK: Factory
+/**
+ * Builds the built-in `url-models` MCP tool definition.
+ *
+ * Matches a pasted app URL against the build-time route manifest and returns the
+ * Firestore models the page renders — model types plus concrete keys with the
+ * route params and `{authUid}` substituted. Optionally filtered to specific
+ * `models`, reduced to keys-only, or loaded via the same permission-checked read
+ * path as `model-get`.
+ *
+ * A URL that matches no state returns a structured `{ matched: null, candidates }`
+ * (not an error) so the caller can suggest near-misses.
+ *
+ * @param deps - The route manifest plus the shared read-documents / identity callbacks.
+ * @returns A statically-registered {@link McpToolDefinition}.
+ */ function createUrlModelsTool(deps) {
+    var handler = function handler(args, ctx) {
+        return urlModelsToolHandler(args, ctx, deps);
+    };
+    var name = URL_MODELS_TOOL_NAME;
+    var description = 'Decode an app URL (or path) into the Firestore models its page renders. Pass a URL like `https://app.example.co/worker/abc/timesheets/list`; the tool matches it against the build-time route manifest and returns each model type plus the concrete key (route params + `{authUid}` substituted). Use `models` to filter to specific types, `keysOnly` for just the resolved keys, or `load: true` to fetch the documents via the same permission-checked path as `model-get` (cannot combine `load` with `keysOnly`).';
+    return buildStaticToolDefinition({
+        name: name,
+        description: description,
+        inputSchema: URL_MODELS_INPUT_SCHEMA,
+        outputSchema: URL_MODELS_OUTPUT_SCHEMA,
+        dispatch: {
+            call: URL_MODELS_DISPATCH_CALL,
+            modelType: URL_MODELS_DISPATCH_MODEL_TYPE
+        },
+        staticHandler: handler,
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
+}
+// MARK: Handler
+function urlModelsToolHandler(args, ctx, deps) {
+    return _async_to_generator$4(function() {
+        var result, input, payload, error;
+        return _ts_generator$4(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    _state.trys.push([
+                        0,
+                        2,
+                        ,
+                        3
+                    ]);
+                    input = parseUrlModelsInput(args);
+                    return [
+                        4,
+                        resolveUrlModels(input, ctx, deps)
+                    ];
+                case 1:
+                    payload = _state.sent();
+                    result = {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(payload)
+                            }
+                        ],
+                        structuredContent: payload
+                    };
+                    return [
+                        3,
+                        3
+                    ];
+                case 2:
+                    error = _state.sent();
+                    result = formatMcpToolErrorResponse(error);
+                    return [
+                        3,
+                        3
+                    ];
+                case 3:
+                    return [
+                        2,
+                        result
+                    ];
+            }
+        });
+    })();
+}
+function parseUrlModelsInput(args) {
+    var url = args.url;
+    if (typeof url !== 'string' || url.length === 0) {
+        throw new Error('url-models: "url" is required and must be a non-empty string.');
+    }
+    var keysOnly = args.keysOnly === true;
+    var load = args.load === true;
+    if (keysOnly && load) {
+        throw new Error('url-models: "keysOnly" and "load" cannot be combined — "keysOnly" returns keys without loading documents.');
+    }
+    var models;
+    if (args.models !== undefined) {
+        if (!Array.isArray(args.models) || args.models.some(function(m) {
+            return typeof m !== 'string';
+        })) {
+            throw new Error('url-models: "models" must be an array of model-type strings.');
+        }
+        models = args.models;
+    }
+    var currentUserUid;
+    if (args.currentUserUid !== undefined) {
+        if (typeof args.currentUserUid !== 'string' || args.currentUserUid.length === 0) {
+            throw new Error('url-models: "currentUserUid" must be a non-empty string.');
+        }
+        currentUserUid = args.currentUserUid;
+    }
+    return _object_spread$1(_object_spread_props$1(_object_spread$1({
+        url: url
+    }, models === undefined ? {} : {
+        models: models
+    }), {
+        keysOnly: keysOnly,
+        load: load
+    }), currentUserUid === undefined ? {} : {
+        currentUserUid: currentUserUid
+    });
+}
+function resolveUrlModels(input, ctx, deps) {
+    return _async_to_generator$4(function() {
+        var matchResult, payload, _tmp;
+        return _ts_generator$4(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    matchResult = matchRouteManifestUrl({
+                        manifest: deps.routeManifest,
+                        url: input.url
+                    });
+                    if (!(matchResult.kind === 'none')) return [
+                        3,
+                        1
+                    ];
+                    payload = {
+                        url: input.url,
+                        pathname: matchResult.pathname,
+                        matched: null,
+                        candidates: matchResult.candidates.map(stateSummary)
+                    };
+                    return [
+                        3,
+                        4
+                    ];
+                case 1:
+                    if (!(matchResult.kind === 'ambiguous')) return [
+                        3,
+                        2
+                    ];
+                    payload = {
+                        url: input.url,
+                        pathname: matchResult.pathname,
+                        matched: null,
+                        ambiguous: matchResult.states.map(stateSummary)
+                    };
+                    return [
+                        3,
+                        4
+                    ];
+                case 2:
+                    _tmp = {
+                        url: input.url,
+                        pathname: matchResult.pathname
+                    };
+                    return [
+                        4,
+                        buildMatchedPayload({
+                            match: matchResult,
+                            input: input,
+                            ctx: ctx,
+                            deps: deps
+                        })
+                    ];
+                case 3:
+                    payload = (_tmp.matched = _state.sent(), _tmp);
+                    _state.label = 4;
+                case 4:
+                    return [
+                        2,
+                        payload
+                    ];
+            }
+        });
+    })();
+}
+function stateSummary(state) {
+    return {
+        name: state.name,
+        fullUrl: state.fullUrl
+    };
+}
+function buildMatchedPayload(args) {
+    return _async_to_generator$4(function() {
+        var _input_currentUserUid, _ctx_auth, match, input, ctx, deps, uid, filtered, resolved, loaded, _tmp;
+        return _ts_generator$4(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    match = args.match, input = args.input, ctx = args.ctx, deps = args.deps;
+                    // `currentUserUid` (when supplied) overrides the uid used to fill `{authUid}` placeholders so a
+                    // caller can preview another user's page-models. The document-load path still uses `ctx.auth`, so
+                    // this is a key-substitution preview only — no privilege escalation on the actual reads.
+                    uid = (_input_currentUserUid = input.currentUserUid) !== null && _input_currentUserUid !== void 0 ? _input_currentUserUid : (_ctx_auth = ctx.auth) === null || _ctx_auth === void 0 ? void 0 : _ctx_auth.uid;
+                    filtered = input.models === undefined ? match.state.models : match.state.models.filter(function(m) {
+                        var _input_models;
+                        return (_input_models = input.models) === null || _input_models === void 0 ? void 0 : _input_models.includes(m.modelType);
+                    });
+                    resolved = filtered.map(function(entry) {
+                        return resolveModelEntry({
+                            entry: entry,
+                            params: match.params,
+                            uid: uid,
+                            keysOnly: input.keysOnly === true,
+                            deps: deps,
+                            ctx: ctx
+                        });
+                    });
+                    if (!(input.load === true)) return [
+                        3,
+                        2
+                    ];
+                    return [
+                        4,
+                        loadResolvedModels(resolved, ctx, deps)
+                    ];
+                case 1:
+                    _tmp = _state.sent();
+                    return [
+                        3,
+                        3
+                    ];
+                case 2:
+                    _tmp = undefined;
+                    _state.label = 3;
+                case 3:
+                    loaded = _tmp;
+                    return [
+                        2,
+                        _object_spread$1({
+                            state: {
+                                name: match.state.name,
+                                fullUrl: match.state.fullUrl,
+                                component: match.state.component,
+                                componentFile: match.state.componentFile
+                            },
+                            via: match.via,
+                            params: match.params,
+                            models: resolved
+                        }, loaded === undefined ? {} : {
+                            loaded: loaded
+                        })
+                    ];
+            }
+        });
+    })();
+}
+function resolveModelEntry(input) {
+    var entry = input.entry, keysOnly = input.keysOnly;
+    var base = keysOnly ? {
+        modelType: entry.modelType,
+        kind: entry.kind
+    } : _object_spread$1({
+        modelType: entry.modelType,
+        kind: entry.kind
+    }, entry.keyTemplate === undefined ? {} : {
+        keyTemplate: entry.keyTemplate
+    }, entry.description === undefined ? {} : {
+        description: entry.description
+    }, entry.from === undefined ? {} : {
+        from: entry.from
+    });
+    var result;
+    if (entry.kind === 'list') {
+        result = base;
+    } else if (entry.kind === 'id') {
+        result = _object_spread$1({}, base, resolveIdKey(input));
+    } else {
+        result = _object_spread$1({}, base, resolveFullKey(input));
+    }
+    return result;
+}
+function resolveIdKey(input) {
+    var _entry_keyTemplate;
+    var entry = input.entry, params = input.params, uid = input.uid, deps = input.deps, ctx = input.ctx;
+    var value = substitutePlaceholder((_entry_keyTemplate = entry.keyTemplate) !== null && _entry_keyTemplate !== void 0 ? _entry_keyTemplate : '', params, uid);
+    var result;
+    if (value.kind === 'unresolved') {
+        result = {
+            unresolved: value.unresolved
+        };
+    } else {
+        var identity = deps.resolveIdentity(entry.modelType, ctx.auth);
+        if (identity == null) {
+            result = {
+                unresolved: {
+                    reason: 'unknown-model-type',
+                    message: "Unknown model type `".concat(entry.modelType, "`.")
+                }
+            };
+        } else if (identity.type === 'root') {
+            result = {
+                key: "".concat(identity.collectionName, "/").concat(value.value)
+            };
+        } else {
+            result = {
+                unresolved: {
+                    reason: 'subcollection-requires-key-template',
+                    message: "Model `".concat(entry.modelType, "` is a subcollection; an `id` key template cannot be promoted to a full key. Annotate it with a full `gb/:id/...` key template.")
+                }
+            };
+        }
+    }
+    return result;
+}
+function resolveFullKey(input) {
+    var _entry_keyTemplate;
+    var entry = input.entry, params = input.params, uid = input.uid;
+    var segments = ((_entry_keyTemplate = entry.keyTemplate) !== null && _entry_keyTemplate !== void 0 ? _entry_keyTemplate : '').split('/');
+    var parts = [];
+    var unresolved;
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = segments[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var segment = _step.value;
+            if (segment.startsWith(':') || segment === AUTH_UID_PLACEHOLDER) {
+                var value = substitutePlaceholder(segment, params, uid);
+                if (value.kind === 'unresolved') {
+                    unresolved = value.unresolved;
+                    break;
+                }
+                parts.push(value.value);
+            } else {
+                parts.push(segment);
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return unresolved === undefined ? {
+        key: parts.join('/')
+    } : {
+        unresolved: unresolved
+    };
+}
+function substitutePlaceholder(segment, params, uid) {
+    var result;
+    if (segment === AUTH_UID_PLACEHOLDER) {
+        result = uid == null || uid.length === 0 ? {
+            kind: 'unresolved',
+            unresolved: {
+                reason: 'auth-required',
+                message: 'This page keys a model by the caller uid (`{authUid}`) but the request is not authenticated.'
+            }
+        } : {
+            kind: 'value',
+            value: uid
+        };
+    } else if (segment.startsWith(':')) {
+        var paramName = segment.slice(1);
+        var value = params[paramName];
+        result = value === undefined ? {
+            kind: 'unresolved',
+            unresolved: {
+                reason: 'missing-param',
+                message: "Route param `:".concat(paramName, "` was not captured from the URL.")
+            }
+        } : {
+            kind: 'value',
+            value: value
+        };
+    } else {
+        result = {
+            kind: 'value',
+            value: segment
+        };
+    }
+    return result;
+}
+// MARK: Load
+function loadResolvedModels(resolved, ctx, deps) {
+    return _async_to_generator$4(function() {
+        var keysByType, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, model, existing, out, _iteratorNormalCompletion1, _didIteratorError1, _iteratorError1, _iterator1, _step1, _step_value, modelType, keys, merged, err;
+        return _ts_generator$4(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    keysByType = new Map();
+                    _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    try {
+                        for(_iterator = resolved[Symbol.iterator](); !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                            model = _step.value;
+                            if (model.key !== undefined) {
+                                existing = keysByType.get(model.modelType);
+                                if (existing === undefined) {
+                                    keysByType.set(model.modelType, [
+                                        model.key
+                                    ]);
+                                } else {
+                                    existing.push(model.key);
+                                }
+                            }
+                        }
+                    } catch (err) {
+                        _didIteratorError = true;
+                        _iteratorError = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                _iterator.return();
+                            }
+                        } finally{
+                            if (_didIteratorError) {
+                                throw _iteratorError;
+                            }
+                        }
+                    }
+                    out = [];
+                    _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
+                    _state.label = 1;
+                case 1:
+                    _state.trys.push([
+                        1,
+                        6,
+                        7,
+                        8
+                    ]);
+                    _iterator1 = keysByType[Symbol.iterator]();
+                    _state.label = 2;
+                case 2:
+                    if (!!(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done)) return [
+                        3,
+                        5
+                    ];
+                    _step_value = _sliced_to_array$2(_step1.value, 2), modelType = _step_value[0], keys = _step_value[1];
+                    return [
+                        4,
+                        readInChunks({
+                            modelType: modelType,
+                            keys: keys,
+                            auth: ctx.auth,
+                            readDocuments: deps.readDocuments
+                        })
+                    ];
+                case 3:
+                    merged = _state.sent();
+                    out.push({
+                        modelType: modelType,
+                        results: merged.results,
+                        errors: merged.errors
+                    });
+                    _state.label = 4;
+                case 4:
+                    _iteratorNormalCompletion1 = true;
+                    return [
+                        3,
+                        2
+                    ];
+                case 5:
+                    return [
+                        3,
+                        8
+                    ];
+                case 6:
+                    err = _state.sent();
+                    _didIteratorError1 = true;
+                    _iteratorError1 = err;
+                    return [
+                        3,
+                        8
+                    ];
+                case 7:
+                    try {
+                        if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
+                            _iterator1.return();
+                        }
+                    } finally{
+                        if (_didIteratorError1) {
+                            throw _iteratorError1;
+                        }
+                    }
+                    return [
+                        7
+                    ];
+                case 8:
+                    return [
+                        2,
+                        out
+                    ];
+            }
+        });
+    })();
+}
+function readInChunks(input) {
+    return _async_to_generator$4(function() {
+        var modelType, keys, auth, readDocuments, merged, offset, _merged_results, _merged_errors, batch, partial;
+        return _ts_generator$4(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    modelType = input.modelType, keys = input.keys, auth = input.auth, readDocuments = input.readDocuments;
+                    merged = {
+                        results: [],
+                        errors: []
+                    };
+                    offset = 0;
+                    _state.label = 1;
+                case 1:
+                    if (!(offset < keys.length)) return [
+                        3,
+                        4
+                    ];
+                    batch = keys.slice(offset, offset + MCP_MODEL_GET_BATCH_SIZE);
+                    return [
+                        4,
+                        readDocuments(modelType, batch, auth)
+                    ];
+                case 2:
+                    partial = _state.sent();
+                    (_merged_results = merged.results).push.apply(_merged_results, _to_consumable_array$3(partial.results));
+                    (_merged_errors = merged.errors).push.apply(_merged_errors, _to_consumable_array$3(partial.errors));
+                    _state.label = 3;
+                case 3:
+                    offset += MCP_MODEL_GET_BATCH_SIZE;
+                    return [
+                        3,
+                        1
+                    ];
+                case 4:
+                    return [
+                        2,
+                        merged
+                    ];
             }
-        }
-    }
+        });
+    })();
 }
 // MARK: Schemas
-var WHOAMI_INPUT_SCHEMA = {
-    type: 'object',
-    properties: {},
-    additionalProperties: false
-};
-var WHOAMI_OUTPUT_SCHEMA = {
+var URL_MODELS_INPUT_SCHEMA = {
     type: 'object',
     required: [
-        'authenticated',
-        'claims',
-        'roles',
-        'claimDetails',
-        'unknownClaimKeys'
+        'url'
     ],
-    description: 'Caller identity, raw token claims, decoded role set, and per-claim descriptions for every key present on the live token.',
     properties: {
-        authenticated: {
-            type: 'boolean'
+        url: {
+            type: 'string',
+            minLength: 1,
+            description: 'Full URL or pathname, e.g. "https://app.example.co/worker/abc/timesheets/list".'
         },
-        uid: {
-            type: 'string'
+        models: {
+            type: 'array',
+            items: {
+                type: 'string'
+            },
+            description: 'Restrict the output to these model types.'
         },
-        email: {
-            type: 'string'
+        keysOnly: {
+            type: 'boolean',
+            description: 'Return only the resolved keys (no descriptions or documents). Cannot combine with "load".'
         },
-        emailVerified: {
-            type: 'boolean'
+        load: {
+            type: 'boolean',
+            description: 'Load each resolved document via the permission-checked read path. Cannot combine with "keysOnly".'
         },
-        app: {
+        currentUserUid: {
+            type: 'string',
+            minLength: 1,
+            description: "Override the uid used to fill `{authUid}` placeholders when resolving model keys (defaults to the authenticated caller). Use to preview the models another user would see on a page. `load` still reads via the calling user's permissions."
+        }
+    },
+    additionalProperties: false
+};
+var URL_MODELS_OUTPUT_SCHEMA = {
+    type: 'object',
+    required: [
+        'url',
+        'pathname',
+        'matched'
+    ],
+    properties: {
+        url: {
             type: 'string'
         },
-        claims: {
-            type: 'object',
-            additionalProperties: true
+        pathname: {
+            type: 'string'
         },
-        roles: {
-            type: 'array',
-            items: {
-                type: 'string'
+        matched: {
+            type: [
+                'object',
+                'null'
+            ],
+            description: 'The matched page and its models, or null when no state matched.',
+            properties: {
+                state: {
+                    type: 'object'
+                },
+                via: {
+                    type: 'string'
+                },
+                params: {
+                    type: 'object'
+                },
+                models: {
+                    type: 'array',
+                    items: {
+                        type: 'object'
+                    }
+                },
+                loaded: {
+                    type: 'array',
+                    items: {
+                        type: 'object'
+                    }
+                }
             }
         },
-        claimDetails: {
+        ambiguous: {
             type: 'array',
             items: {
-                type: 'object',
-                required: [
-                    'key',
-                    'description',
-                    'grantedRoles',
-                    'inverse',
-                    'tags'
-                ],
-                properties: {
-                    key: {
-                        type: 'string'
-                    },
-                    interfaceName: {
-                        type: 'string'
-                    },
-                    description: {
-                        type: 'string'
-                    },
-                    grantedRoles: {
-                        type: 'array',
-                        items: {
-                            type: 'string'
-                        }
-                    },
-                    inverse: {
-                        type: 'boolean'
-                    },
-                    tags: {
-                        type: 'array',
-                        items: {
-                            type: 'string'
-                        }
-                    }
-                }
-            }
+                type: 'object'
+            },
+            description: 'Competing states when the URL matched more than one.'
         },
-        unknownClaimKeys: {
+        candidates: {
             type: 'array',
             items: {
-                type: 'string'
-            }
+                type: 'object'
+            },
+            description: 'Closest near-miss states when nothing matched.'
         }
     }
 };
@@ -3046,7 +4848,7 @@ function _non_iterable_rest$1() {
 function _sliced_to_array$1(arr, i) {
     return _array_with_holes$1(arr) || _iterable_to_array_limit$1(arr, i) || _unsupported_iterable_to_array$3(arr, i) || _non_iterable_rest$1();
 }
-function _type_of$1(obj) {
+function _type_of$2(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
@@ -3220,7 +5022,7 @@ function _ts_generator$3(thisArg, body) {
     };
     var name = BATCH_EXECUTE_TOOL_NAME;
     var description = 'Execute a batch of MCP operations server-side from an uploaded JSON/NDJSON file, returning a success/failure summary. Each line/element is an operation `{ call, modelType, specifier?, data }` matching any other write tool you could call individually. Generate the file with a script and upload it instead of invoking a per-record tool many times. Every operation is authorized against your visible tools before any run; a forbidden or malformed operation aborts the whole batch with nothing executed.';
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: BATCH_EXECUTE_INPUT_SCHEMA,
@@ -3230,20 +5032,11 @@ function _ts_generator$3(thisArg, body) {
             modelType: BATCH_EXECUTE_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: false
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: BATCH_EXECUTE_INPUT_SCHEMA,
-            outputSchema: BATCH_EXECUTE_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: false,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function batchExecuteToolHandler(args, ctx, deps) {
@@ -3440,7 +5233,7 @@ function parseJsonArrayOperations(fileText) {
     return parsed;
 }
 function validateOperation(value, index) {
-    if (value == null || (typeof value === "undefined" ? "undefined" : _type_of$1(value)) !== 'object') {
+    if (value == null || (typeof value === "undefined" ? "undefined" : _type_of$2(value)) !== 'object') {
         throw new Error("batch-execute: operation[".concat(index, "] must be an object."));
     }
     var candidate = value;
@@ -3932,12 +5725,50 @@ function _non_iterable_rest() {
 function _non_iterable_spread$2() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property$3(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
 function _sliced_to_array(arr, i) {
     return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array$2(arr, i) || _non_iterable_rest();
 }
 function _to_consumable_array$2(arr) {
     return _array_without_holes$2(arr) || _iterable_to_array$2(arr) || _unsupported_iterable_to_array$2(arr) || _non_iterable_spread$2();
 }
+function _type_of$1(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
 function _unsupported_iterable_to_array$2(o, minLen) {
     if (!o) return;
     if (typeof o === "string") return _array_like_to_array$2(o, minLen);
@@ -4066,10 +5897,14 @@ var McpServerFactoryService_1;
         _define_property$3(this, "_cachedStaticTools", void 0);
         _define_property$3(this, "_cachedManifest", void 0);
         _define_property$3(this, "_cachedManifestModels", void 0);
+        _define_property$3(this, "_cachedManifestEnums", void 0);
         _define_property$3(this, "_cachedManifestAuth", void 0);
+        _define_property$3(this, "_cachedRouteManifest", void 0);
+        _define_property$3(this, "_routeManifestLoaded", false);
         _define_property$3(this, "_manifestLoaded", false);
         _define_property$3(this, "_loggedSkips", false);
         _define_property$3(this, "_warnedMissingRoleReader", false);
+        _define_property$3(this, "_resolvedReasonConfig", void 0);
         _define_property$3(this, "_analyticsService", void 0);
         this.mcpConfig = mcpConfig;
         this.dispatchService = dispatchService;
@@ -4341,15 +6176,39 @@ var McpServerFactoryService_1;
                                 return getService.getModelIdentity(modelType, auth);
                             }
                         }));
+                        // `url-models` reuses the model-get read/identity path, so it is only offered when the get
+                        // service is wired AND a route manifest with at least one state was loaded.
+                        var routeManifest = this._resolveRouteManifest();
+                        if (routeManifest != null && routeManifest.states.length > 0) {
+                            staticTools.push(createUrlModelsTool({
+                                routeManifest: routeManifest,
+                                readDocuments: function readDocuments(modelType, keys, auth) {
+                                    return getService.readDocuments(modelType, keys, auth);
+                                },
+                                resolveIdentity: function resolveIdentity(modelType, auth) {
+                                    return getService.getModelIdentity(modelType, auth);
+                                }
+                            }));
+                        }
                     }
                     var modelManifest = this._cachedManifestModels;
+                    var enumManifest = this._cachedManifestEnums;
                     if (modelManifest != null && modelManifest.length > 0) {
-                        staticTools.push(createModelInfoTool({
+                        staticTools.push(createModelInfoTool(_object_spread({
                             manifest: modelManifest
-                        }), createModelDecodeTool({
+                        }, enumManifest == null ? {} : {
+                            enums: enumManifest
+                        })), createModelDecodeTool({
                             manifest: modelManifest
                         }));
                     }
+                    // `enum-info` only needs the enum value tables — register it whenever the manifest carries a
+                    // non-empty `enums` block, independent of the model catalog.
+                    if (enumManifest != null && Object.keys(enumManifest).length > 0) {
+                        staticTools.push(createEnumInfoTool({
+                            enums: enumManifest
+                        }));
+                    }
                     var authManifest = this._cachedManifestAuth;
                     if (authManifest != null) {
                         staticTools.push(createWhoamiTool({
@@ -4511,9 +6370,55 @@ var McpServerFactoryService_1;
             value: function _resetManifestCache() {
                 this._cachedManifest = undefined;
                 this._cachedManifestModels = undefined;
+                this._cachedManifestEnums = undefined;
                 this._cachedManifestAuth = undefined;
             }
         },
+        {
+            /**
+     * Reads the pre-rendered route manifest JSON once, validates its version, and caches the result
+     * for the process lifetime. Drives whether the built-in `url-models` static tool is registered.
+     *
+     * Missing file or wrong version fall back to "no route manifest" with a single boot warning;
+     * the `url-models` tool is then simply not offered.
+     *
+     * @returns The cached route manifest, or `undefined` when none was loaded.
+     */ key: "_resolveRouteManifest",
+            value: function _resolveRouteManifest() {
+                if (!this._routeManifestLoaded) {
+                    this._routeManifestLoaded = true;
+                    var path = this.mcpConfig.mcpRouteManifestPath;
+                    if (path == null) {
+                        this._cachedRouteManifest = undefined;
+                    } else if (existsSync(path)) {
+                        this._parseRouteManifestFile(path);
+                    } else {
+                        this._logger.warn("MCP route manifest path is set but the file is missing: ".concat(path, ". The url-models tool will not be registered."));
+                        this._cachedRouteManifest = undefined;
+                    }
+                }
+                return this._cachedRouteManifest;
+            }
+        },
+        {
+            key: "_parseRouteManifestFile",
+            value: function _parseRouteManifestFile(path) {
+                try {
+                    var raw = readFileSync(path, 'utf8');
+                    var parsed = JSON.parse(raw);
+                    if (parsed.version === ROUTE_MANIFEST_VERSION) {
+                        this._cachedRouteManifest = parsed;
+                        this._logger.log("Loaded MCP route manifest from ".concat(path, ": ").concat(parsed.states.length, " states."));
+                    } else {
+                        this._logger.warn("MCP route manifest version mismatch at ".concat(path, ": got ").concat(String(parsed.version), ", expected ").concat(ROUTE_MANIFEST_VERSION, ". The url-models tool will not be registered."));
+                        this._cachedRouteManifest = undefined;
+                    }
+                } catch (error) {
+                    this._logger.warn("Failed to read MCP route manifest at ".concat(path, ": ").concat(error.message, ". The url-models tool will not be registered."));
+                    this._cachedRouteManifest = undefined;
+                }
+            }
+        },
         {
             key: "_parseManifestFile",
             value: function _parseManifestFile(path) {
@@ -4560,11 +6465,14 @@ var McpServerFactoryService_1;
                 }
                 var models = Array.isArray(parsed.models) && parsed.models.length > 0 ? parsed.models : undefined;
                 var modelSuffix = models == null ? '' : ", ".concat(models.length, " model entries");
+                var enums = parsed.enums != null && _type_of$1(parsed.enums) === 'object' && Object.keys(parsed.enums).length > 0 ? parsed.enums : undefined;
+                var enumSuffix = enums == null ? '' : ", ".concat(Object.keys(enums).length, " enum entries");
                 var auth = parsed.auth != null && Array.isArray(parsed.auth.claims) ? parsed.auth : undefined;
                 var authSuffix = auth == null ? '' : ", ".concat(auth.claims.length, " auth claim entries");
-                this._logger.log("Loaded MCP manifest from ".concat(path, ": ").concat(map.size, " tool entries").concat(modelSuffix).concat(authSuffix, "."));
+                this._logger.log("Loaded MCP manifest from ".concat(path, ": ").concat(map.size, " tool entries").concat(modelSuffix).concat(enumSuffix).concat(authSuffix, "."));
                 this._cachedManifest = map;
                 this._cachedManifestModels = models;
+                this._cachedManifestEnums = enums;
                 this._cachedManifestAuth = auth;
             }
         },
@@ -4699,11 +6607,32 @@ var McpServerFactoryService_1;
         },
         {
             /**
+     * Resolves the app's reason-parameter config once and caches it for the process lifetime.
+     *
+     * The underlying {@link McpModuleConfig.reasonParameter} value is fixed at boot, so the normalized
+     * form is safe to memoize and reuse across every `tools/list` and `tools/call`.
+     *
+     * @returns The resolved reason-parameter config (defaults applied).
+     */ key: "_resolveReasonConfig",
+            value: function _resolveReasonConfig() {
+                var result = this._resolvedReasonConfig;
+                if (result == null) {
+                    result = resolveMcpReasonParameterConfig(this.mcpConfig.reasonParameter);
+                    this._resolvedReasonConfig = result;
+                }
+                return result;
+            }
+        },
+        {
+            /**
      * Resolves the wire-shape `tools/list` entry for a single tool.
      *
      * Hot-path short-circuit: tools without a `toolDetailsBuilder` reuse the precomputed,
      * frozen {@link McpToolDefinition.staticWireEntry} verbatim — zero allocations per
-     * request for the common case.
+     * request for the common case. When the auto-injected reason parameter is enabled (the
+     * default), the entry is no longer returned frozen-verbatim: its `inputSchema` is wrapped
+     * with the reason property per request (`tools/list` is low-frequency, so the allocation is
+     * acceptable). Tools that already declare the parameter name are still reused verbatim.
      *
      * Tools that opted in to {@link McpToolDetailsBuilder} get a fresh wire entry built
      * from the builder's overrides. If the builder throws, the framework falls back to
@@ -4715,9 +6644,20 @@ var McpServerFactoryService_1;
      * @returns The wire-shape entry to emit for this tool on `tools/list`.
      */ key: "_buildToolListEntry",
             value: function _buildToolListEntry(tool, ctx, scopes) {
+                var reasonConfig = this._resolveReasonConfig();
                 var result;
                 if (tool.toolDetailsBuilder == null) {
                     result = tool.staticWireEntry;
+                    if (reasonConfig.enabled) {
+                        var reasoned = applyMcpReasonParameterToSchema(tool.staticWireEntry.inputSchema, reasonConfig);
+                        // applyMcpReasonParameterToSchema self-skips (returns the same reference) on collision, so the
+                        // frozen-verbatim hot path still holds for tools that already declare the parameter name.
+                        if (reasoned !== tool.staticWireEntry.inputSchema) {
+                            result = _object_spread_props(_object_spread({}, tool.staticWireEntry), {
+                                inputSchema: reasoned
+                            });
+                        }
+                    }
                 } else {
                     var description = tool.description;
                     var inputSchema = tool.inputSchema;
@@ -4738,16 +6678,23 @@ var McpServerFactoryService_1;
                     } catch (error) {
                         this._logger.warn("MCP tool ".concat(tool.name, " toolDetails builder threw; falling back to defaults: ").concat(error.message));
                     }
+                    var resolvedInputSchema = inputSchema !== null && inputSchema !== void 0 ? inputSchema : {
+                        type: 'object'
+                    };
+                    if (reasonConfig.enabled) {
+                        resolvedInputSchema = applyMcpReasonParameterToSchema(resolvedInputSchema, reasonConfig);
+                    }
                     var wire = {
                         name: tool.name,
                         description: description,
-                        inputSchema: inputSchema !== null && inputSchema !== void 0 ? inputSchema : {
-                            type: 'object'
-                        }
+                        inputSchema: resolvedInputSchema
                     };
                     if (tool.outputSchema != null) {
                         wire.outputSchema = tool.outputSchema;
                     }
+                    if (tool.annotations != null) {
+                        wire.annotations = tool.annotations;
+                    }
                     result = wire;
                 }
                 return result;
@@ -4770,14 +6717,20 @@ var McpServerFactoryService_1;
      * @returns The MCP tool response.
      */ function _handleToolCall(request, definitionsByName, ctx) {
                 return _async_to_generator$2(function() {
-                    var _request_params_arguments, _ctx_auth, toolName, definition, args, startedAt, outcome, isSuccessful, toolKind;
+                    var _request_params_arguments, _ctx_auth, toolName, definition, rawArgs, startedAt, reasonConfig, declaresOwn, _extractMcpReasonFromArgs, reason, args, outcome, isSuccessful, toolKind;
                     return _ts_generator$2(this, function(_state) {
                         switch(_state.label){
                             case 0:
                                 toolName = request.params.name;
                                 definition = definitionsByName.get(toolName);
-                                args = (_request_params_arguments = request.params.arguments) !== null && _request_params_arguments !== void 0 ? _request_params_arguments : {};
+                                rawArgs = (_request_params_arguments = request.params.arguments) !== null && _request_params_arguments !== void 0 ? _request_params_arguments : {};
                                 startedAt = Date.now();
+                                // Split the auto-injected reason out of the args: forward it to analytics, but never let it reach
+                                // the underlying handler. Tools that declare their own field of the same name keep it (driven by
+                                // the tool's own resolved inputSchema, not the reason-augmented wire schema).
+                                reasonConfig = this._resolveReasonConfig();
+                                declaresOwn = mcpSchemaDeclaresProperty(definition === null || definition === void 0 ? void 0 : definition.inputSchema, reasonConfig.parameterName);
+                                _extractMcpReasonFromArgs = extractMcpReasonFromArgs(rawArgs, reasonConfig, declaresOwn), reason = _extractMcpReasonFromArgs.reason, args = _extractMcpReasonFromArgs.args;
                                 if (!(definition == null)) return [
                                     3,
                                     1
@@ -4827,6 +6780,7 @@ var McpServerFactoryService_1;
                                     auth: ctx.auth,
                                     readOnly: this.mcpConfig.readOnly === true,
                                     args: args,
+                                    reason: reason,
                                     isSuccessful: isSuccessful,
                                     error: outcome.error,
                                     durationMs: Date.now() - startedAt
@@ -5668,18 +7622,20 @@ var FirebaseServerMcpAnalyticsService_1;
                 if (this._logEvents) {
                     var uidSuffix = event.uid ? " uid=".concat(event.uid) : '';
                     var durationSuffix = event.durationMs == null ? '' : " (".concat(event.durationMs, "ms)");
+                    var reasonSuffix = event.reason ? ' reason="'.concat(event.reason, '"') : '';
                     var outcome = event.isSuccessful ? 'Succeeded' : 'Failed';
-                    this._logger.log("MCP ".concat(event.toolName, " [").concat(event.toolKind, "] ").concat(outcome).concat(uidSuffix).concat(durationSuffix));
+                    this._logger.log("MCP ".concat(event.toolName, " [").concat(event.toolKind, "] ").concat(outcome).concat(uidSuffix).concat(durationSuffix).concat(reasonSuffix));
                 }
                 if (this.analyticsService != null) {
-                    var _event_call, _event_modelType, _event_specifier;
+                    var _event_call, _event_modelType, _event_specifier, _event_reason;
                     this.analyticsService.sendEventData(event.uid, this._eventName, {
                         tool: event.toolName,
                         toolKind: event.toolKind,
                         call: (_event_call = event.call) !== null && _event_call !== void 0 ? _event_call : '',
                         modelType: (_event_modelType = event.modelType) !== null && _event_modelType !== void 0 ? _event_modelType : '',
                         specifier: (_event_specifier = event.specifier) !== null && _event_specifier !== void 0 ? _event_specifier : '',
-                        success: event.isSuccessful
+                        success: event.isSuccessful,
+                        reason: (_event_reason = event.reason) !== null && _event_reason !== void 0 ? _event_reason : ''
                     });
                 }
             }
@@ -5766,4 +7722,4 @@ function _unsupported_iterable_to_array(o, minLen) {
     };
 }
 
-export { BATCH_EXECUTE_DISPATCH_CALL, BATCH_EXECUTE_DISPATCH_MODEL_TYPE, BATCH_EXECUTE_TOOL_NAME, DEFAULT_BATCH_EXECUTE_MAX_PARALLEL, DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS, DEFAULT_MCP_ANALYTICS_EVENT_NAME, DEFAULT_MCP_PATH, DEFAULT_MCP_SERVER_INSTRUCTIONS, DEFAULT_MCP_SERVER_NAME, DEFAULT_SPECIFIER_KEY, DEFAULT_VOID_MCP_SUCCESS_VALUE, FIREBASE_SERVER_MCP_ANALYTICS_CONFIG, FIREBASE_SERVER_MCP_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, FirebaseServerMcpAnalyticsService, MAX_BATCH_EXECUTE_FILE_BYTES, MAX_BATCH_EXECUTE_OPERATIONS, MCP_ANALYTICS_SERVICE, MCP_AUTH_ROLE_READER, MCP_CALL_TYPE_ABBREVIATIONS, MCP_MANIFEST_VERSION, MCP_MODEL_GET_BATCH_SIZE, MCP_TOOL_NAME_MAX_LENGTH, MCP_TOOL_NAME_WARN_LENGTH, MODEL_DECODE_DISPATCH_CALL, MODEL_DECODE_DISPATCH_MODEL_TYPE, MODEL_DECODE_TOOL_NAME, MODEL_GET_DISPATCH_CALL, MODEL_GET_DISPATCH_MODEL_TYPE, MODEL_GET_TOOL_NAME, MODEL_INFO_DISPATCH_CALL, MODEL_INFO_DISPATCH_MODEL_TYPE, MODEL_INFO_GROUPS_HINT, MODEL_INFO_TOOL_NAME, MODEL_INFO_UNGROUPED_LABEL, McpAnalyticsService, McpController, McpModuleConfig, McpServerFactoryService, McpWellKnownController, abbreviateMcpCallType, appMcpAnalyticsModuleMetadata, batchOperationCoordKey, buildDefaultMcpToolDescription, buildDisambiguatedMcpToolName, buildMcpToolName, buildStaticWireEntry, classifyVisibility, createBatchExecuteTool, createModelDecodeTool, createModelGetTool, createModelInfoTool, decodeFirestoreModelKey, findModelEntry, formatMcpToolErrorResponse, formatMcpToolResponse, generateMcpToolDefinitions, handleStreamableHttpMcpRequest, mcpManifestKey, mcpModuleMetadata, noopMcpAnalyticsService, resolveEffectiveReadOnly, resolveRequiredScope, validateMcpToolName };
+export { BATCH_EXECUTE_DISPATCH_CALL, BATCH_EXECUTE_DISPATCH_MODEL_TYPE, BATCH_EXECUTE_TOOL_NAME, DEFAULT_BATCH_EXECUTE_MAX_PARALLEL, DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS, DEFAULT_MCP_ANALYTICS_EVENT_NAME, DEFAULT_MCP_PATH, DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION, DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH, DEFAULT_MCP_REASON_PARAMETER_NAME, DEFAULT_MCP_REASON_PARAMETER_REQUIRED, DEFAULT_MCP_SERVER_INSTRUCTIONS, DEFAULT_MCP_SERVER_NAME, DEFAULT_SPECIFIER_KEY, DEFAULT_VOID_MCP_SUCCESS_VALUE, ENUM_INFO_DISPATCH_CALL, ENUM_INFO_DISPATCH_MODEL_TYPE, ENUM_INFO_TOOL_NAME, ENUM_TABLE_SCHEMA, FIREBASE_SERVER_MCP_ANALYTICS_CONFIG, FIREBASE_SERVER_MCP_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, FirebaseServerMcpAnalyticsService, MAX_BATCH_EXECUTE_FILE_BYTES, MAX_BATCH_EXECUTE_OPERATIONS, MCP_ANALYTICS_SERVICE, MCP_AUTH_ROLE_READER, MCP_CALL_TYPE_ABBREVIATIONS, MCP_MANIFEST_VERSION, MCP_MODEL_GET_BATCH_SIZE, MCP_TOOL_NAME_MAX_LENGTH, MCP_TOOL_NAME_WARN_LENGTH, MCP_WRITE_TOOL_DESCRIPTION_PREFIX, MODEL_DECODE_DISPATCH_CALL, MODEL_DECODE_DISPATCH_MODEL_TYPE, MODEL_DECODE_TOOL_NAME, MODEL_GET_DISPATCH_CALL, MODEL_GET_DISPATCH_MODEL_TYPE, MODEL_GET_TOOL_NAME, MODEL_INFO_DISPATCH_CALL, MODEL_INFO_DISPATCH_MODEL_TYPE, MODEL_INFO_GROUPS_HINT, MODEL_INFO_TOOL_NAME, MODEL_INFO_UNGROUPED_LABEL, McpAnalyticsService, McpController, McpModuleConfig, McpServerFactoryService, McpWellKnownController, ROUTE_MANIFEST_VERSION, URL_MODELS_DISPATCH_CALL, URL_MODELS_DISPATCH_MODEL_TYPE, URL_MODELS_TOOL_NAME, abbreviateMcpCallType, appMcpAnalyticsModuleMetadata, applyMcpReasonParameterToSchema, applyWriteMarker, batchOperationCoordKey, buildDefaultMcpToolDescription, buildDisambiguatedMcpToolName, buildMcpToolName, buildStaticToolDefinition, buildStaticWireEntry, classifyVisibility, createBatchExecuteTool, createEnumInfoTool, createModelDecodeTool, createModelGetTool, createModelInfoTool, createUrlModelsTool, decodeFirestoreModelKey, extractMcpReasonFromArgs, findModelEntry, formatMcpToolErrorResponse, formatMcpToolResponse, generateMcpToolDefinitions, handleStreamableHttpMcpRequest, matchRouteManifestUrl, mcpManifestKey, mcpModuleMetadata, mcpSchemaDeclaresProperty, noopMcpAnalyticsService, parseUrlModelsPathname, resolveEffectiveReadOnly, resolveEnumInfoOutput, resolveMcpReasonParameterConfig, resolveMcpToolAnnotations, resolveRequiredScope, validateMcpToolName };