firebase · joehan · Sep 1, 2026 · Sep 1, 2026 · Sep 1, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,4 @@
+- Add `humanReadableDescription` field to MCP tools and use it in `--generate-tool-list` output.
 - Fixed an issue where the Functions emulator replaced an IPC failure with an unrelated `TypeError` about stream chunk types, hiding why the runtime became unreachable (#10876).
 - [Added] Add -f, --force option to `firebase ext:migrate`.
 - [Fixed] Fix parameter type preservation and optional system parameter handling during extension updates in `firebase ext:migrate`
diff --git a/src/mcp/CONTRIBUTING.md b/src/mcp/CONTRIBUTING.md
@@ -92,9 +92,11 @@ import { tool } from "../../tool";
 import { mcpError, toContent } from "../../util";
 
 export const foo_bar = tool(
+  "<product>",
   {
     name: "foo_bar",
     description: "Foos a bar. This description informs LLMs when to use this tool",
+    humanReadableDescription: "Foos a bar.",
     inputSchema: z.object({
       foo: z
         .string()
@@ -138,7 +140,8 @@ Here are a few style notes:
   - should be all lower-case letters
   - should be snake case
 - Descriptions
-  - should be aimed at informing LLMs, not humans
+  - `description` should be aimed at informing LLMs, not humans
+  - `humanReadableDescription` should be a short, 1 sentence description of what the tool does for human-facing documentation
 
 #### Load the command
 

diff --git a/src/mcp/README.md b/src/mcp/README.md
diff --git a/src/mcp/tool.spec.ts b/src/mcp/tool.spec.ts
@@ -26,12 +26,13 @@
  });

  it("should create a tool with the correct shape and properties", () => {
    const testFn = async () => ({ content: [] });
    const testTool = tool(
      "core",
       {
         name: "test_tool",
         description: "A test tool",
+        humanReadableDescription: "A short human readable description.",
         inputSchema: z.object({}),
         outputSchema: z.object({ result: z.string() }),
       },
@@ -40,8 +41,9 @@
 
     expect(testTool.mcp.name).to.equal("test_tool");
     expect(testTool.mcp.description).to.equal("A test tool");
+    expect(testTool.mcp.humanReadableDescription).to.equal("A short human readable description.");
     expect(testTool.mcp.outputSchema).to.not.be.undefined;
     expect(testTool.mcp.outputSchema.properties.result.type).to.equal("string");
     expect(testTool.fn).to.equal(testFn);
  });

@@ -104,11 +106,11 @@
        async () => ({ content: [] }),
      );

      const schema = testTool.mcp.inputSchema;
      expect(schema.type).to.equal("object");
      expect(schema.properties).to.have.keys(["req", "opt", "def"]);
      expect(schema.required).to.deep.equal(["req"]);
      expect(schema.properties.def.default).to.equal("hi");
    });

    it("omits `required` entirely when all fields are optional", () => {
@@ -124,9 +126,9 @@
        async () => ({ content: [] }),
      );

      const schema = testTool.mcp.inputSchema;
      expect(schema.properties).to.have.keys(["opt", "def"]);
      expect(schema.required).to.be.undefined;
    });
  });
 });
diff --git a/src/mcp/tool.ts b/src/mcp/tool.ts
@@ -23,6 +23,7 @@ export interface ServerTool<InputSchema extends ZodTypeAny = z.ZodAny> {
   mcp: {
     name: string;
     description?: string;
+    humanReadableDescription?: string;
     inputSchema: any;
     outputSchema?: any;
     annotations?: {

diff --git a/src/mcp/tools/apphosting/fetch_logs.ts b/src/mcp/tools/apphosting/fetch_logs.ts
@@ -13,6 +13,7 @@ export const fetch_logs = tool(
     name: "fetch_logs",
     description:
       "Use this to fetch the most recent logs for a specified App Hosting backend. If `buildLogs` is specified, the logs from the build process for the latest build are returned. The most recent logs are listed first.",
+    humanReadableDescription: "Fetch recent service or build logs for an App Hosting backend.",
     inputSchema: z.object({
       buildLogs: z
         .boolean()

diff --git a/src/mcp/tools/apphosting/list_backends.ts b/src/mcp/tools/apphosting/list_backends.ts
@@ -24,6 +24,8 @@ export const list_backends = tool(
       "  Every backend should have a `DEFAULT` domain. " +
       "  The actual domain that a user would use to connect to the backend is the last parameter of the domain resource name. " +
       "  If a custom domain is correctly set up, it will have statuses ending in `ACTIVE`.",
+    humanReadableDescription:
+      "List App Hosting backends, traffic configurations, and custom domains in your project.",
     inputSchema: z.object({
       location: z
         .string()

diff --git a/src/mcp/tools/apptesting/tests.ts b/src/mcp/tools/apptesting/tests.ts
@@ -49,6 +49,8 @@ export const run_tests = tool(
   {
     name: "run_test",
     description: `Run a remote test.`,
+    humanReadableDescription:
+      "Run an automated test case on a remote Android or iOS device via Firebase App Distribution.",
     inputSchema: z.object({
       appId: ApplicationIdSchema,
       releaseBinaryFile: z.string().describe("Path to the binary release (APK)."),
@@ -83,6 +85,8 @@ export const check_status = tool(
     name: "check_status",
     description:
       "Check the status of an apptesting release test and/or get available devices that can be used for automated tests ",
+    humanReadableDescription:
+      "Check the status of an automated release test or list available test devices.",
     inputSchema: z.object({
       release_test_name: z
         .string()

diff --git a/src/mcp/tools/auth/get_users.ts b/src/mcp/tools/auth/get_users.ts
@@ -9,6 +9,8 @@ export const get_users = tool(
     name: "get_users",
     description:
       "Use this to retrieve one or more Firebase Auth users based on a list of UIDs or a list of emails.",
+    humanReadableDescription:
+      "Retrieve Firebase Auth users by UID, email, phone number, or list all users.",
     inputSchema: z.object({
       uids: z.array(z.string()).optional().describe("A list of user UIDs to retrieve."),
       emails: z.array(z.string()).optional().describe("A list of user emails to retrieve."),

diff --git a/src/mcp/tools/auth/set_sms_region_policy.ts b/src/mcp/tools/auth/set_sms_region_policy.ts
@@ -9,6 +9,8 @@ export const set_sms_region_policy = tool(
     name: "set_sms_region_policy",
     description:
       "Use this to set an SMS region policy for Firebase Authentication to restrict the regions which can receive text messages based on an ALLOW or DENY list of country codes. This policy will override any existing policies when set.",
+    humanReadableDescription:
+      "Set an SMS region policy allowing or denying specific country codes for Firebase Authentication.",
     inputSchema: z.object({
       policy_type: z
         .enum(["ALLOW", "DENY"])

diff --git a/src/mcp/tools/auth/update_user.ts b/src/mcp/tools/auth/update_user.ts
@@ -8,6 +8,8 @@ export const update_user = tool(
   {
     name: "update_user",
     description: "Use this to disable, enable, or set a custom claim on a specific user's account.",
+    humanReadableDescription:
+      "Update a user's account by enabling/disabling it or setting custom claims.",
     inputSchema: z.object({
       uid: z.string().describe("the UID of the user to update"),
       disabled: z.boolean().optional().describe("true disables the user, false enables the user"),

diff --git a/src/mcp/tools/core/create_android_sha.ts b/src/mcp/tools/core/create_android_sha.ts
@@ -20,6 +20,8 @@ export const create_android_sha = tool(
     name: "create_android_sha",
     description:
       "Use this to add the specified SHA certificate hash to the specified Firebase Android App.",
+    humanReadableDescription:
+      "Add a SHA-1 or SHA-256 certificate hash to an Android app in the active Firebase project.",
     inputSchema: z.object({
       app_id: z.string().describe("The Android app ID to add the SHA certificate to."),
       sha_hash: z.string().describe("The SHA certificate hash to add (SHA-1 or SHA-256)."),

diff --git a/src/mcp/tools/core/create_app.ts b/src/mcp/tools/core/create_app.ts
@@ -13,6 +13,8 @@ export const create_app = tool(
     name: "create_app",
     description:
       "Use this to create a new Firebase App in the currently active Firebase Project. Firebase Apps can be iOS, Android, or Web.",
+    humanReadableDescription:
+      "Create a new iOS, Android, or Web app in the active Firebase project.",
     inputSchema: z.object({
       display_name: z
         .string()

diff --git a/src/mcp/tools/core/create_project.ts b/src/mcp/tools/core/create_project.ts
@@ -29,6 +29,8 @@ export const create_project = tool(
   {
     name: "create_project",
     description: "Use this to create a new Firebase Project.",
+    humanReadableDescription:
+      "Create a new Firebase project or enable Firebase services on an existing Google Cloud project.",
     inputSchema: z.object({
       project_id: z.string().describe("The project ID to create or use."),
       display_name: z

diff --git a/src/mcp/tools/core/deploy.ts b/src/mcp/tools/core/deploy.ts
@@ -23,6 +23,8 @@ export const deploy = tool(
     name: "deploy",
     description:
       "Deploy resources to your Firebase project, based on the contents of firebase.json.",
+    humanReadableDescription:
+      "Deploy Firebase services and resources configured in firebase.json to your project.",
     inputSchema: z.object({
       only: z
         .string()

diff --git a/src/mcp/tools/core/deploy_status.ts b/src/mcp/tools/core/deploy_status.ts
@@ -8,6 +8,7 @@ export const deploy_status = tool(
   {
     name: "deploy_status",
     description: "Check the status of a background deployment job using its Job ID.",
+    humanReadableDescription: "Check the status and progress of a background deployment job.",
     inputSchema: z.object({
       jobId: z.string().describe("The Job ID returned by the deploy tool"),
     }),

diff --git a/src/mcp/tools/core/get_environment.ts b/src/mcp/tools/core/get_environment.ts
@@ -101,6 +101,8 @@ export const get_environment = tool(
     name: "get_environment",
     description:
       "Use this to retrieve the current Firebase **environment** configuration for the Firebase CLI and Firebase MCP server, including current authenticated user, project directory, active Firebase Project, and more. All tools require the user to be authenticated, but not all information is required for all tools. Pay attention to the tool requirements for which pieces of information are required.",
+    humanReadableDescription:
+      "Retrieve the current Firebase CLI and MCP environment configuration, active project, and authenticated user.",
     inputSchema: z.object({}),
     annotations: {
       title: "Get Firebase Environment Info",

diff --git a/src/mcp/tools/core/get_project.ts b/src/mcp/tools/core/get_project.ts
@@ -8,6 +8,8 @@ export const get_project = tool(
   {
     name: "get_project",
     description: "Use this to retrieve information about the currently active Firebase Project.",
+    humanReadableDescription:
+      "Retrieve metadata and configuration details for the currently active Firebase project.",
     inputSchema: z.object({}),
     annotations: {
       title: "Get Current Firebase Project",

diff --git a/src/mcp/tools/core/get_sdk_config.ts b/src/mcp/tools/core/get_sdk_config.ts
@@ -10,6 +10,8 @@ export const get_sdk_config = tool(
     description:
       "Use this to retrieve the Firebase configuration information for a Firebase App. " +
       "You must specify EITHER a platform OR the Firebase App ID for a Firebase App registered in the currently active Firebase Project.",
+    humanReadableDescription:
+      "Retrieve SDK configuration details or config file contents for a registered Firebase app.",
     inputSchema: z.object({
       platform: z
         .enum(["ios", "android", "web"])

diff --git a/src/mcp/tools/core/get_security_rules.ts b/src/mcp/tools/core/get_security_rules.ts
@@ -13,6 +13,8 @@ export const get_security_rules = tool(
     description:
       "Use this to retrieve the security rules for a specified Firebase service. " +
       "If there are multiple instances of that service in the product, the rules for the default instance are returned.",
+    humanReadableDescription:
+      "Retrieve the active security rules for Firestore, Storage, or Realtime Database.",
     inputSchema: z.object({
       type: z.enum(["firestore", "rtdb", "storage"]).describe("The service to get rules for."),
       // TODO: Add a resourceID argument that lets you choose non default buckets/dbs.

diff --git a/src/mcp/tools/core/init.ts b/src/mcp/tools/core/init.ts
@@ -21,6 +21,8 @@ export const init = tool(
       "Use this to initialize selected Firebase services in the workspace (Cloud Firestore database, Firebase SQL Connect, Firebase Realtime Database, Firebase AI Logic). All services are optional; specify only the products you want to set up. " +
       "You can initialize new features into an existing project directory, but re-initializing an existing feature may overwrite configuration. " +
       "To deploy the initialized features, run the `firebase deploy` command after `firebase_init` tool.",
+    humanReadableDescription:
+      "Initialize and configure Firebase services in your local project workspace.",
     inputSchema: z.object({
       features: z.object({
         database: z

diff --git a/src/mcp/tools/core/list_apps.ts b/src/mcp/tools/core/list_apps.ts
@@ -9,6 +9,7 @@ export const list_apps = tool(
     name: "list_apps",
     description:
       "Use this to retrieve a list of the Firebase Apps registered in the currently active Firebase project. Firebase Apps can be iOS, Android, or Web.",
+    humanReadableDescription: "List all Firebase apps registered in the active project.",
     inputSchema: z.object({
       platform: z
         .enum(["ios", "android", "web", "all"])

diff --git a/src/mcp/tools/core/list_projects.ts b/src/mcp/tools/core/list_projects.ts
@@ -11,6 +11,7 @@ export const list_projects = tool(
     name: "list_projects",
     description:
       "Use this to retrieve a list of Firebase Projects that the signed-in user has access to.",
+    humanReadableDescription: "List Firebase projects accessible by the authenticated user.",
     inputSchema: z.object({
       page_size: z
         .number()

diff --git a/src/mcp/tools/core/login.ts b/src/mcp/tools/core/login.ts
@@ -61,6 +61,8 @@ export const login = tool(
 }
 \`\`\`
 `,
+    humanReadableDescription:
+      "Sign the user into the Firebase CLI and MCP server or check current authentication status.",
     inputSchema: LoginInputSchema,
     _meta: {
       requiresAuth: false,

diff --git a/src/mcp/tools/core/logout.ts b/src/mcp/tools/core/logout.ts
@@ -15,6 +15,7 @@ export const logout = tool(
   {
     name: "logout",
     description: "Use this to sign the user out of the Firebase CLI and Firebase MCP server.",
+    humanReadableDescription: "Sign the user out of the Firebase CLI and MCP server.",
     inputSchema: z.object({
       email: z
         .string()

diff --git a/src/mcp/tools/core/read_resources.ts b/src/mcp/tools/core/read_resources.ts
@@ -10,6 +10,8 @@ export const read_resources = tool(
     name: "read_resources",
     description:
       "Use this to read the contents of `firebase://` resources or list available resources",
+    humanReadableDescription:
+      "Read the contents of internal firebase:// documentation resources or list all available resources.",
     annotations: {
       title: "Read Firebase Resources",
       destructiveHint: false,

diff --git a/src/mcp/tools/core/update_environment.ts b/src/mcp/tools/core/update_environment.ts
@@ -11,6 +11,8 @@ export const update_environment = tool(
     name: "update_environment",
     description:
       "Use this to update environment config for the Firebase CLI and Firebase MCP server, such as project directory, active project, active user account, accept terms of service, and more. Use `firebase_get_environment` to see the currently configured environment.",
+    humanReadableDescription:
+      "Update environment settings such as project directory, active project, or active user account.",
     inputSchema: z.object({
       project_dir: z
         .string()

diff --git a/src/mcp/tools/core/validate_security_rules.ts b/src/mcp/tools/core/validate_security_rules.ts
@@ -71,6 +71,8 @@ export const validate_security_rules = tool(
     name: "validate_security_rules",
     description:
       "Use this to check Firebase Security Rules for Firestore, Storage, or Realtime Database for syntax and validation errors.",
+    humanReadableDescription:
+      "Validate syntax and check for errors in Firestore, Storage, or Realtime Database security rules.",
     inputSchema: z.object({
       type: z.enum(["firestore", "storage", "rtdb"]),
       source: z

diff --git a/src/mcp/tools/crashlytics/events.ts b/src/mcp/tools/crashlytics/events.ts
@@ -125,6 +125,8 @@ export const list_events = tool(
     description: `Use this to list the most recent events matching the given filters.
       Can be used to fetch sample crashes and exceptions for an issue,
       which will include stack traces and other data useful for debugging.`,
+    humanReadableDescription:
+      "List recent crash and exception events matching specified filters for an issue.",
     inputSchema: z.object({
       appId: ApplicationIdSchema,
       filter: EventFilterSchema,
@@ -172,6 +174,8 @@ export const batch_get_events = tool(
     description: `Gets specific events by resource name.
       Can be used to fetch sample crashes and exceptions for an issue,
       which will include stack traces and other data useful for debugging.`,
+    humanReadableDescription:
+      "Retrieve sample crash and exception events by resource name for debugging.",
     inputSchema: z.object({
       appId: ApplicationIdSchema,
       names: z

diff --git a/src/mcp/tools/crashlytics/issues.ts b/src/mcp/tools/crashlytics/issues.ts
@@ -13,6 +13,7 @@ export const get_issue = tool(
   {
     name: "get_issue",
     description: `Gets data for a Crashlytics issue, which can be used as a starting point for debugging.`,
+    humanReadableDescription: "Retrieve details and metadata for a specific Crashlytics issue.",
     inputSchema: z.object({
       appId: ApplicationIdSchema,
       issueId: IssueIdSchema,
@@ -50,6 +51,7 @@ export const update_issue = tool(
   {
     name: "update_issue",
     description: "Use this to update the state of Crashlytics issue.",
+    humanReadableDescription: "Update the state (OPEN or CLOSED) of a Crashlytics issue.",
     inputSchema: z.object({
       appId: ApplicationIdSchema,
       issueId: IssueIdSchema,

diff --git a/src/mcp/tools/crashlytics/notes.ts b/src/mcp/tools/crashlytics/notes.ts
@@ -10,6 +10,7 @@ export const create_note = tool(
     name: "create_note",
     description:
       "Add a note to an issue from crashlytics. Only supported for mobile (Android and iOS) apps.",
+    humanReadableDescription: "Add a note to a Crashlytics issue for an Android or iOS app.",
     inputSchema: z.object({
       appId: ApplicationIdSchema,
       issueId: IssueIdSchema,
@@ -38,6 +39,8 @@ export const list_notes = tool(
     name: "list_notes",
     description:
       "Use this to list all notes for an issue in Crashlytics. Only supported for mobile (Android and iOS) apps.",
+    humanReadableDescription:
+      "List all notes attached to a Crashlytics issue for an Android or iOS app.",
     inputSchema: z.object({
       appId: ApplicationIdSchema,
       issueId: IssueIdSchema,
@@ -65,6 +68,7 @@ export const delete_note = tool(
     name: "delete_note",
     description:
       "Delete a note from a Crashlytics issue. Only supported for mobile (Android and iOS) apps.",
+    humanReadableDescription: "Delete a note from a Crashlytics issue for an Android or iOS app.",
     inputSchema: z.object({
       appId: ApplicationIdSchema,
       issueId: IssueIdSchema,

diff --git a/src/mcp/tools/crashlytics/reports.ts b/src/mcp/tools/crashlytics/reports.ts
@@ -44,6 +44,8 @@ export const get_report = tool(
     description:
       `Use this to request numerical reports from Crashlytics. The result aggregates the sum of events and impacted users, grouped by a dimension appropriate for that report. Agents must read the [Firebase Crashlytics Reports Guide](firebase://guides/crashlytics/reports) using the \`firebase_read_resources\` tool before calling to understand critical prerequisites for requesting reports and how to interpret the results.
     `.trim(),
+    humanReadableDescription:
+      "Generate aggregated numerical reports for Crashlytics issues and events.",
     inputSchema: ReportInputSchema,
     annotations: {
       title: "Get Crashlytics Report",

diff --git a/src/mcp/tools/dataconnect/compile.ts b/src/mcp/tools/dataconnect/compile.ts
@@ -29,6 +29,8 @@ Resolves service directories defined in the project's \`firebase.json\` under \`
   "error_filter": "schema"
 }
 \`\`\``,
+    humanReadableDescription:
+      "Compile Firebase SQL Connect schemas, operations, and connectors to validate syntax and types.",
     inputSchema: z.object({
       error_filter: z
         .enum(["all", "schema", "operations"])

diff --git a/src/mcp/tools/dataconnect/execute.ts b/src/mcp/tools/dataconnect/execute.ts
@@ -13,6 +13,8 @@ export const execute = tool(
     name: "execute",
     description:
       "Use this to execute a GraphQL operation against a SQL Connect service or its emulator.",
+    humanReadableDescription:
+      "Execute a GraphQL query or mutation against a Firebase SQL Connect service or emulator.",
     inputSchema: z.object({
       query: z.string().describe(`A Firebase SQL Connect GraphQL query or mutation to execute.
 You can use the \`dataconnect_generate_operation\` tool to generate a query.

diff --git a/src/mcp/tools/dataconnect/list_services.ts b/src/mcp/tools/dataconnect/list_services.ts
@@ -29,6 +29,8 @@ export const list_services = tool(
   {
     name: "list_services",
     description: "Use this to list existing local and backend Firebase SQL Connect services",
+    humanReadableDescription:
+      "List local and deployed Firebase SQL Connect services, schemas, and connectors.",
     inputSchema: z.object({}),
     annotations: {
       title: "List existing Firebase SQL Connect services",

diff --git a/src/mcp/tools/firestore/query_collection.ts b/src/mcp/tools/firestore/query_collection.ts
@@ -11,6 +11,8 @@ export const query_collection = tool(
     name: "query_collection",
     description:
       "Use this to retrieve one or more Firestore documents from a collection in a database in the current project by a collection with a full document path. Use this if you know the exact path of a collection and the filtering clause you would like for the document.",
+    humanReadableDescription:
+      "Query Firestore documents from a collection with optional filters and ordering.",
     inputSchema: z.object({
       database: z
         .string()

diff --git a/src/mcp/tools/functions/get_logs.ts b/src/mcp/tools/functions/get_logs.ts
@@ -47,6 +47,8 @@ export const get_logs = tool(
     name: "get_logs",
     description:
       "Use this to retrieve a page of Cloud Functions log entries using Google Cloud Logging advanced filters.",
+    humanReadableDescription:
+      "Retrieve and filter Cloud Functions log entries from Google Cloud Logging.",
     inputSchema: z.object({
       function_names: z
         .array(z.string())

diff --git a/src/mcp/tools/functions/list_functions.ts b/src/mcp/tools/functions/list_functions.ts
@@ -11,6 +11,7 @@ export const list_functions = tool(
   {
     name: "list_functions",
     description: "List all deployed functions in your Firebase project.",
+    humanReadableDescription: "List all deployed Cloud Functions in your Firebase project.",
     inputSchema: z.object({}),
     annotations: {
       title: "List Deployed Functions",