@dereekb/firebase-server 13.17.0 → 13.19.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$8(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$8(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$8(obj, key, value) {
      * discovery document. Claude custom-connector reads this to discover the OIDC issuer.
      *
      * @example 'https://api.example.com/oidc'
-     */ _define_property$8(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$8(obj, key, value) {
      * and used as the audience the access token's `aud` claim should match.
      *
      * @example 'https://api.example.com/mcp'
-     */ _define_property$8(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$8(this, "serverName", void 0);
+     */ _define_property$9(this, "serverName", void 0);
     /**
      * Optional version advertised on the MCP `initialize` handshake.
-     */ _define_property$8(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$8(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,7 @@ function _define_property$8(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$8(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
@@ -109,7 +126,7 @@ function _define_property$8(obj, key, value) {
      * 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$8(this, "mcpRouteManifestPath", void 0);
+     */ _define_property$9(this, "mcpRouteManifestPath", void 0);
     /**
      * When `true`, the MCP server only advertises tools whose effective read-only classification is `true`.
      *
@@ -119,19 +136,29 @@ function _define_property$8(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$8(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$4(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$4(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;
 }
@@ -145,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");
@@ -947,6 +1174,46 @@ function _unsupported_iterable_to_array$8(o, minLen) {
  */ 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.
@@ -1644,7 +1911,7 @@ function _ts_generator$5(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,
@@ -1654,20 +1921,11 @@ function _ts_generator$5(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) {
@@ -1938,7 +2196,7 @@ function _object_spread$4(target) {
     }
     return target;
 }
-function ownKeys$1(object, enumerableOnly) {
+function ownKeys$2(object, enumerableOnly) {
     var keys = Object.keys(object);
     if (Object.getOwnPropertySymbols) {
         var symbols = Object.getOwnPropertySymbols(object);
@@ -1946,12 +2204,12 @@ function ownKeys$1(object, enumerableOnly) {
     }
     return keys;
 }
-function _object_spread_props$1(target, source) {
+function _object_spread_props$2(target, source) {
     source = source != null ? source : {};
     if (Object.getOwnPropertyDescriptors) {
         Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
     } else {
-        ownKeys$1(Object(source)).forEach(function(key) {
+        ownKeys$2(Object(source)).forEach(function(key) {
             Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
         });
     }
@@ -2015,7 +2273,7 @@ function _unsupported_iterable_to_array$6(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,
@@ -2025,20 +2283,11 @@ function _unsupported_iterable_to_array$6(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) {
@@ -2142,7 +2391,7 @@ function resolveModelInfoOutput(input, manifest) {
             }
         }
         if (tables.length > 0) {
-            result = _object_spread_props$1(_object_spread$4({}, output), {
+            result = _object_spread_props$2(_object_spread$4({}, output), {
                 enums: tables
             });
         }
@@ -2196,7 +2445,7 @@ function parseModelInfoInput(args) {
     var modelGroup = parseModelGroupArg(args['modelGroup']);
     var all = parseBooleanArg(args['all'], 'all');
     var fields = parseBooleanArg(args['fields'], 'fields');
-    return _object_spread$4(_object_spread_props$1(_object_spread$4(_object_spread_props$1(_object_spread$4({}, modelQueries == null ? {} : {
+    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'])
@@ -2694,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$1(_object_spread$4({}, 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: {
@@ -2829,7 +3078,7 @@ function _object_spread$3(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,
@@ -2839,20 +3088,11 @@ function _object_spread$3(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) {
@@ -3059,7 +3299,7 @@ var MODEL_DECODE_OUTPUT_SCHEMA = {
     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 {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: ENUM_INFO_INPUT_SCHEMA,
@@ -3069,20 +3309,11 @@ var MODEL_DECODE_OUTPUT_SCHEMA = {
             modelType: ENUM_INFO_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: ENUM_INFO_INPUT_SCHEMA,
-            outputSchema: ENUM_INFO_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function enumInfoToolHandler(args, _ctx, deps) {
@@ -3339,13 +3570,13 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  */ function createWhoamiTool(deps) {
     var _ref;
     var _deps_auth_app;
-    var handler = function handler(_args, ctx) {
-        return Promise.resolve(whoamiToolHandler(ctx, deps));
+    var handler = function handler(args, ctx) {
+        return Promise.resolve(whoamiToolHandler(args, ctx, deps));
     };
     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 {
+    var description = "Reports the authenticated caller's identity and decoded role set for `".concat(appLabel, '`. Returns `authenticated: false` for anonymous callers. Defaults to a concise summary (uid + roles only); pass `detail: "claims"` to also include the raw claims object, or `detail: "full"` to additionally include per-claim descriptions (drawn from the build-time auth manifest) and any unknown claim keys.');
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: WHOAMI_INPUT_SCHEMA,
@@ -3355,38 +3586,25 @@ function _unsupported_iterable_to_array$5(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) {
+function whoamiToolHandler(args, ctx, deps) {
     var _auth_token;
     var _deps_auth_app;
     var auth = ctx.auth;
     if ((auth === null || auth === void 0 ? void 0 : auth.uid) == null) {
-        var output = {
-            authenticated: false,
-            claims: {},
-            roles: [],
-            claimDetails: [],
-            unknownClaimKeys: []
-        };
-        return buildResult(output, '# whoami\n\nUnauthenticated.');
+        return buildResult({
+            authenticated: false
+        }, '# whoami\n\nNot authenticated (anonymous caller).');
     }
+    var detail = parseDetailLevel(args);
     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$3(param, 2), value = _param[1];
-        return value !== undefined;
+    var claimKeys = Object.entries(token).filter(function(param) {
+        var _param = _sliced_to_array$3(param, 2), key = _param[0], value = _param[1];
+        return value !== undefined && key !== 'email' && key !== 'email_verified';
     }).map(function(param) {
         var _param = _sliced_to_array$3(param, 1), key = _param[0];
         return key;
@@ -3420,11 +3638,8 @@ function whoamiToolHandler(ctx, deps) {
     var unknownClaimKeys = [];
     var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
     try {
-        for(var _iterator1 = presentKeys[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
+        for(var _iterator1 = claimKeys[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
             var key = _step1.value;
-            if (key === 'email' || key === 'email_verified') {
-                continue;
-            }
             var claim1 = claimsByKey.get(key);
             if (claim1 == null) {
                 unknownClaimKeys.push(key);
@@ -3454,22 +3669,30 @@ function whoamiToolHandler(ctx, deps) {
             }
         }
     }
-    var output1 = _object_spread$2({
+    var output = _object_spread$2({
         authenticated: true,
         uid: auth.uid,
-        claims: _object_spread$2({}, token),
         roles: roles,
-        claimDetails: claimDetails,
-        unknownClaimKeys: unknownClaimKeys
+        claimCount: claimKeys.length
     }, ((_deps_auth_app = deps.auth.app) === null || _deps_auth_app === void 0 ? void 0 : _deps_auth_app.app) == null ? {} : {
         app: deps.auth.app.app
     }, token.email == null ? {} : {
         email: token.email
     }, token.email_verified == null ? {} : {
         emailVerified: token.email_verified
-    });
-    var text = renderText(output1);
-    return buildResult(output1, text);
+    }, detail === 'summary' ? {} : {
+        claims: _object_spread$2({}, token)
+    }, detail === 'full' ? {
+        claimDetails: claimDetails,
+        unknownClaimKeys: unknownClaimKeys
+    } : {});
+    var text = renderText(output, detail);
+    return buildResult(output, text);
+}
+// Coerces the `detail` input into a WhoamiDetailLevel, defaulting unknown or absent values to `summary`.
+function parseDetailLevel(args) {
+    var value = args.detail;
+    return value === 'claims' || value === 'full' ? value : 'summary';
 }
 function buildResult(output, text) {
     return {
@@ -3482,34 +3705,51 @@ function buildResult(output, text) {
         structuredContent: output
     };
 }
-function renderText(output) {
+function renderText(output, detail) {
     var lines = [
         '# whoami',
         ''
     ];
     appendHeaderLines(lines, output);
-    appendClaimDetailLines(lines, output.claimDetails);
-    appendUnknownClaimLines(lines, output.unknownClaimKeys);
+    if (detail === 'full') {
+        var _output_claimDetails, _output_unknownClaimKeys;
+        appendClaimDetailLines(lines, (_output_claimDetails = output.claimDetails) !== null && _output_claimDetails !== void 0 ? _output_claimDetails : []);
+        appendUnknownClaimLines(lines, (_output_unknownClaimKeys = output.unknownClaimKeys) !== null && _output_unknownClaimKeys !== void 0 ? _output_unknownClaimKeys : []);
+    }
+    if (detail !== 'summary') {
+        var _output_claims;
+        appendRawClaimsLines(lines, (_output_claims = output.claims) !== null && _output_claims !== void 0 ? _output_claims : {});
+    }
+    appendDetailHint(lines, detail);
     return lines.join('\n');
 }
 function appendHeaderLines(lines, output) {
-    if (output.uid != null) {
-        lines.push("- **uid:** `".concat(output.uid, "`"));
-    }
-    if (output.app != null) {
-        lines.push("- **app:** `".concat(output.app, "`"));
-    }
+    var _output_roles, _output_claimCount;
+    var appPart = output.app == null ? '' : " on `".concat(output.app, "`");
+    lines.push("Authenticated as `".concat(output.uid, "`").concat(appPart, "."), '');
     if (output.email != null) {
-        lines.push("- **email:** `".concat(output.email, "`"));
+        lines.push("- **email:** `".concat(output.email, "`").concat(formatEmailVerified(output.emailVerified)));
     }
-    if (output.roles.length > 0) {
-        var rolesText = output.roles.map(function(role) {
+    var roles = (_output_roles = output.roles) !== null && _output_roles !== void 0 ? _output_roles : [];
+    if (roles.length > 0) {
+        var rolesText = roles.map(function(role) {
             return "`".concat(role, "`");
         }).join(', ');
         lines.push("- **roles:** ".concat(rolesText));
     } else {
         lines.push('- **roles:** _(none)_');
     }
+    lines.push("- **claims:** ".concat((_output_claimCount = output.claimCount) !== null && _output_claimCount !== void 0 ? _output_claimCount : 0, " present"));
+}
+// Renders the parenthetical verification suffix for the email line, or an empty string when the token carries no `email_verified` claim.
+function formatEmailVerified(emailVerified) {
+    if (emailVerified === true) {
+        return ' (verified)';
+    }
+    if (emailVerified === false) {
+        return ' (unverified)';
+    }
+    return '';
 }
 function appendClaimDetailLines(lines, claimDetails) {
     if (claimDetails.length === 0) {
@@ -3571,22 +3811,40 @@ function appendUnknownClaimLines(lines, unknownClaimKeys) {
         }
     }
 }
+// Renders the raw claims object as a fenced JSON block — the one place the tool emits raw JSON, since claims are an arbitrary key → value bag.
+function appendRawClaimsLines(lines, claims) {
+    lines.push('', '## Raw claims', '```json', JSON.stringify(claims, null, 2), '```');
+}
+// Appends a hint pointing at the next, more detailed level. Omitted at `full`, which is already the most detailed level.
+function appendDetailHint(lines, detail) {
+    if (detail === 'summary') {
+        lines.push('', '_Call again with `detail: "claims"` for the raw claim values, or `detail: "full"` for values plus per-claim descriptions._');
+    } else if (detail === 'claims') {
+        lines.push('', '_Call again with `detail: "full"` for per-claim descriptions and unknown claim keys._');
+    }
+}
 // MARK: Schemas
 var WHOAMI_INPUT_SCHEMA = {
     type: 'object',
-    properties: {},
+    properties: {
+        detail: {
+            type: 'string',
+            enum: [
+                'summary',
+                'claims',
+                'full'
+            ],
+            description: 'Level of detail. "summary" (default): identity + decoded roles only. "claims": adds the raw claims object (key → value). "full": adds per-claim descriptions, granted/revoked roles, tags, and unknown claim keys.'
+        }
+    },
     additionalProperties: false
 };
 var WHOAMI_OUTPUT_SCHEMA = {
     type: 'object',
     required: [
-        'authenticated',
-        'claims',
-        'roles',
-        'claimDetails',
-        'unknownClaimKeys'
+        'authenticated'
     ],
-    description: 'Caller identity, raw token claims, decoded role set, and per-claim descriptions for every key present on the live token.',
+    description: 'Caller identity and decoded role set. Claim-bearing fields (claims, claimDetails, unknownClaimKeys) are present only at the detail level that requests them via the `detail` input.',
     properties: {
         authenticated: {
             type: 'boolean'
@@ -3603,16 +3861,19 @@ var WHOAMI_OUTPUT_SCHEMA = {
         app: {
             type: 'string'
         },
-        claims: {
-            type: 'object',
-            additionalProperties: true
-        },
         roles: {
             type: 'array',
             items: {
                 type: 'string'
             }
         },
+        claimCount: {
+            type: 'integer'
+        },
+        claims: {
+            type: 'object',
+            additionalProperties: true
+        },
         claimDetails: {
             type: 'array',
             items: {
@@ -3762,7 +4023,7 @@ function _object_spread$1(target) {
     }
     return target;
 }
-function ownKeys(object, enumerableOnly) {
+function ownKeys$1(object, enumerableOnly) {
     var keys = Object.keys(object);
     if (Object.getOwnPropertySymbols) {
         var symbols = Object.getOwnPropertySymbols(object);
@@ -3770,12 +4031,12 @@ function ownKeys(object, enumerableOnly) {
     }
     return keys;
 }
-function _object_spread_props(target, source) {
+function _object_spread_props$1(target, source) {
     source = source != null ? source : {};
     if (Object.getOwnPropertyDescriptors) {
         Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
     } else {
-        ownKeys(Object(source)).forEach(function(key) {
+        ownKeys$1(Object(source)).forEach(function(key) {
             Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
         });
     }
@@ -3929,7 +4190,7 @@ function _ts_generator$4(thisArg, body) {
     };
     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 {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: URL_MODELS_INPUT_SCHEMA,
@@ -3939,20 +4200,11 @@ function _ts_generator$4(thisArg, body) {
             modelType: URL_MODELS_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: URL_MODELS_INPUT_SCHEMA,
-            outputSchema: URL_MODELS_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function urlModelsToolHandler(args, ctx, deps) {
@@ -4029,7 +4281,7 @@ function parseUrlModelsInput(args) {
         }
         currentUserUid = args.currentUserUid;
     }
-    return _object_spread$1(_object_spread_props(_object_spread$1({
+    return _object_spread$1(_object_spread_props$1(_object_spread$1({
         url: url
     }, models === undefined ? {} : {
         models: models
@@ -4809,7 +5061,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,
@@ -4819,20 +5071,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) {
@@ -5536,6 +5779,25 @@ function _object_spread(target) {
     }
     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();
 }
@@ -5681,6 +5943,7 @@ var McpServerFactoryService_1;
         _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;
@@ -6383,11 +6646,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
@@ -6399,9 +6683,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;
@@ -6422,12 +6717,16 @@ 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;
@@ -6457,14 +6756,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
@@ -6514,6 +6819,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
@@ -7355,18 +7661,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 : ''
                     });
                 }
             }
@@ -7453,4 +7761,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, 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, applyWriteMarker, batchOperationCoordKey, buildDefaultMcpToolDescription, buildDisambiguatedMcpToolName, buildMcpToolName, buildStaticWireEntry, classifyVisibility, createBatchExecuteTool, createEnumInfoTool, createModelDecodeTool, createModelGetTool, createModelInfoTool, createUrlModelsTool, decodeFirestoreModelKey, findModelEntry, formatMcpToolErrorResponse, formatMcpToolResponse, generateMcpToolDefinitions, handleStreamableHttpMcpRequest, matchRouteManifestUrl, mcpManifestKey, mcpModuleMetadata, noopMcpAnalyticsService, parseUrlModelsPathname, resolveEffectiveReadOnly, resolveEnumInfoOutput, resolveMcpToolAnnotations, 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 };