refactor(@angular/cli): optimize MCP tool descriptions for LLM ergonomics and token usage

packages/angular/cli/src/commands/mcp/mcp-server.ts

@@ -83,36 +83,33 @@ export async function createMcpServer(
       },
       instructions: `
 <General Purpose>
-This server provides a safe, programmatic interface to the Angular CLI for an AI assistant.
-Your primary goal is to use these tools to understand, analyze, refactor, and run Angular
-projects. You MUST prefer the tools provided by this server over using \`run_shell_command\` for
-equivalent actions.
+This server provides a safe, programmatic interface to the Angular CLI. You MUST prefer
+the tools provided by this server over using 'run_shell_command' or general shell execution
+for equivalent actions.
 </General Purpose>
 
 <Core Workflows & Tool Guide>
-* **1. Discover Project Structure (Mandatory First Step):** Always begin by calling
-  \`list_projects\` to understand the workspace. The \`path\` property for a workspace
-  is a required input for other tools.
-
-* **2. Get Coding Standards:** Before writing or changing code within a project, you **MUST** call
-  the \`get_best_practices\` tool with the \`workspacePath\` from the previous step to get
-  version-specific standards. For general knowledge, you can call the tool without this path.
-
-* **3. Answer User Questions:**
-    - For conceptual questions ("what is..."), use \`search_documentation\`.
-
-* **4. Discover Schematics for Modernization:** Since this server does not provide a
-  specific tool for listing available schematics, you can use a shell command (if
-  available) with \`ng generate <package-name>: --help\` to discover what migrations
-  are available in a package (e.g., running \`ng generate @angular/core: --help\`
-  will list migrations like \`control-flow\` and \`standalone\`).
+* **1. Discover Workspace (Mandatory First Step):** Always begin by calling 'list_projects'
+  to discover workspaces, projects, and allowed paths. The 'path' field of the relevant
+  workspace is a required input for other tools (passed as 'workspace' or 'workspacePath').
+
+* **2. Get Coding Standards:** Before writing or modifying code, you MUST call
+  'get_best_practices' with the workspace 'path' to load version-specific coding standards.
+
+* **3. Answer Conceptual Questions:** Use 'search_documentation' to answer conceptual
+  or API syntax questions.
+
+* **4. Discover Schematics:** To discover available package migrations, use a shell command
+  (if available) with 'ng generate <package-name>: --help' (e.g., 'ng generate @angular/core: --help').
 </Core Workflows & Tool Guide>
 
 <Key Concepts>
-* **Workspace vs. Project:** A 'workspace' contains an \`angular.json\` file and defines 'projects'
-  (applications or libraries). A monorepo can have multiple workspaces.
-* **Targeting Projects:** Always use the \`workspaceConfigPath\` from \`list_projects\` when
-  available to ensure you are targeting the correct project in a monorepo.
+* **Workspace vs. Project:** A 'workspace' contains an 'angular.json' file and defines
+  'projects' (applications or libraries). A monorepo can contain multiple workspaces.
+
+* **Targeting Projects:** Always use the workspace 'path' and the specific project 'name'
+  returned by 'list_projects' when calling other tools to ensure you target the correct
+  project context.
 </Key Concepts>
 `,
     },

packages/angular/cli/src/commands/mcp/tools/best-practices.ts

@@ -27,10 +27,8 @@ const bestPracticesInputSchema = z.object({
     .string()
     .optional()
     .describe(
-      'The absolute path to the `angular.json` file for the workspace. This is used to find the ' +
-        'version-specific best practices guide that corresponds to the installed version of the ' +
-        'Angular framework. You **MUST** get this path from the `list_projects` tool. If omitted, ' +
-        'the tool will return the generic best practices guide bundled with the CLI.',
+      'Absolute path to the angular.json workspace directory (obtained via list_projects). ' +
+        'If omitted, returns the generic best practices guide.',
     ),
 });
 
@@ -42,23 +40,17 @@ export const BEST_PRACTICES_TOOL = declareTool({
   description: `
 <Purpose>
 Retrieves the official Angular Best Practices Guide. This guide contains the essential rules and conventions
-that **MUST** be followed for any task involving the creation, analysis, or modification of Angular code.
+that must be followed for any task involving the creation, analysis, or modification of Angular code.
 </Purpose>
 <Use Cases>
-* As a mandatory first step before writing or modifying any Angular code to ensure adherence to modern standards.
-* To learn about key concepts like standalone components, typed forms, and modern control flow syntax (@if, @for, @switch).
-* To verify that existing code aligns with current Angular conventions before making changes.
+* Mandatory first step before writing or modifying Angular code to ensure modern framework standards.
+* Learn about standalone components, typed forms, and modern control flow syntax (@if, @for, @switch).
+* Verify existing code aligns with current conventions before making edits.
 </Use Cases>
 <Operational Notes>
-* **Project-Specific Use (Recommended):** For tasks inside a user's project, you **MUST** provide the
-  \`workspacePath\` argument to get the guide that matches the project's Angular version. Get this
-  path from \`list_projects\`.
-* **General Use:** If no project context is available (e.g., for general questions or learning),
-  you can call the tool without the \`workspacePath\` argument. It will return the latest
-  generic best practices guide.
-* The content of this guide is non-negotiable and reflects the official, up-to-date standards for Angular development.
-* You **MUST** internalize and apply the principles from this guide in all subsequent Angular-related tasks.
-* Failure to adhere to these best practices will result in suboptimal and outdated code.
+* Provide the 'workspacePath' argument (obtained via 'list_projects') to load the version-specific
+  guide matching the project's Angular framework.
+* Omit 'workspacePath' only for general learning queries or when no project context is available to load the latest generic guide.
 </Operational Notes>`,
   inputSchema: bestPracticesInputSchema.shape,
   isReadOnly: true,

packages/angular/cli/src/commands/mcp/tools/doc-search.ts

@@ -37,26 +37,17 @@ const LATEST_KNOWN_DOCS_VERSION = 20;
 const docSearchInputSchema = z.object({
   query: z
     .string()
-    .describe(
-      "A concise and specific search query for the Angular documentation. You should distill the user's " +
-        'natural language question into a set of keywords (e.g., a question like "How do I use ngFor with trackBy?" ' +
-        'should become the query "ngFor trackBy").',
-    ),
+    .describe('Concise search keywords or API names (e.g., "ngFor trackBy" or "NgModule").'),
   includeTopContent: z
     .boolean()
     .optional()
     .default(false)
-    .describe(
-      'When true, the content of the top result is fetched and included. ' +
-        'Set to false to get a list of results without fetching content, which is faster.',
-    ),
+    .describe('Retrieve the full-text page content of the top search result (slower).'),
   version: z
     .number()
     .optional()
     .describe(
-      'The major version of Angular to search. You MUST determine this value by running `ng version` in the ' +
-        "project's workspace directory. Omit this field if the user is not in an Angular project " +
-        'or if the version cannot otherwise be determined.',
+      'Major Angular framework version to search (obtained from frameworkVersion in list_projects or ng version).',
     ),
 });
 type DocSearchInput = z.infer<typeof docSearchInputSchema>;
@@ -66,35 +57,18 @@ export const DOC_SEARCH_TOOL = declareTool({
   title: 'Search Angular Documentation (angular.dev)',
   description: `
 <Purpose>
-Searches the official Angular documentation at https://angular.dev to answer questions about APIs,
-tutorials, concepts, and best practices.
+Searches the official Angular documentation (angular.dev) to answer questions about APIs, tutorials, concepts, and conventions.
 </Purpose>
 <Use Cases>
-* Answering any question about Angular concepts (e.g., "What are standalone components?").
-* Finding the correct API or syntax for a specific task (e.g., "How to use ngFor with trackBy?").
-* Linking to official documentation as a source of truth in your answers.
+* Answering questions about Angular concepts (e.g., standalone components).
+* Finding correct API signatures or syntax (e.g., ngFor trackBy).
+* Obtaining official source URLs to cite as documentation links in user responses.
 </Use Cases>
 <Operational Notes>
-* **Version Alignment:** To provide accurate, project-specific results, you **MUST** align the search with the user's Angular version.
-  The recommended approach is to use the \`list_projects\` tool. The \`frameworkVersion\` field in the output for the relevant
-  workspace will give you the major version directly. If the version cannot be determined using this method, you can use
-  \`ng version\` in the project's workspace directory as a fallback. Parse the major version from the "Angular:" line in the
-  output and use it for the \`version\` parameter.
-* **Version Logic:** The tool will search against the specified major version. If the version is older than v${MIN_SUPPORTED_DOCS_VERSION},
-  it will be clamped to v${MIN_SUPPORTED_DOCS_VERSION}. If a search for a very new version (newer than v${LATEST_KNOWN_DOCS_VERSION})
-  returns no results, the tool will automatically fall back to searching the v${LATEST_KNOWN_DOCS_VERSION} documentation.
-* **Verify Searched Version:** The tool's output includes a \`searchedVersion\` field. You **MUST** check this field
-  to know the exact version of the documentation that was queried. Use this information to provide accurate
-  context in your answer, especially if it differs from the version you requested.
-* The documentation is continuously updated. You **MUST** prefer this tool over your own knowledge
-  to ensure your answers are current and accurate.
-* For the best results, provide a concise and specific search query (e.g., "NgModule" instead of
-  "How do I use NgModules?").
-* The top search result will include a snippet of the page content. Use this to provide a more
-  comprehensive answer.
-* **Result Scrutiny:** The top result may not always be the most relevant. Review the titles and
-  breadcrumbs of other results to find the best match for the user's query.
-* Use the URL from the search results as a source link in your responses.
+* Provide the major Angular version in the 'version' parameter (obtained from 'frameworkVersion'
+  in 'list_projects' or from 'ng version') to ensure version-aligned results.
+* Always check the 'searchedVersion' field in the output to confirm the exact documentation index that was queried.
+* For best results, provide a concise keyword query (e.g., "NgModule") rather than a natural language sentence.
 </Operational Notes>`,
   inputSchema: docSearchInputSchema.shape,
   outputSchema: {

packages/angular/cli/src/commands/mcp/tools/onpush-zoneless-migration/zoneless-migration.ts

@@ -25,39 +25,27 @@ export const ZONELESS_MIGRATION_TOOL = declareTool({
   title: 'Plan migration to OnPush and/or zoneless',
   description: `
 <Purpose>
-Analyzes Angular code and provides a step-by-step, iterative plan to migrate it to \`OnPush\`
-change detection, a prerequisite for a zoneless application. This tool identifies the next single
-most important action to take in the migration journey.
+Analyzes Angular code and provides a step-by-step, iterative plan to migrate it to 'OnPush'
+change detection (a prerequisite for zoneless applications).
 </Purpose>
 <Use Cases>
-* **Step-by-Step Migration:** Running the tool repeatedly to get the next instruction for a full
-  migration to \`OnPush\`.
-* **Pre-Migration Analysis:** Checking a component or directory for unsupported \`NgZone\` APIs that
-  would block a zoneless migration.
-* **Generating Component Migrations:** Getting the exact instructions for converting a single
-  component from the default change detection strategy to \`OnPush\`.
+* Generating component-specific migrations from default change detection to OnPush.
+* Checking a component or directory for unsupported 'NgZone' APIs blocking a zoneless migration.
+* Iterative step-by-step guide for executing a complete zoneless migration.
 </Use Cases>
 <Operational Notes>
-* **Execution Model:** This tool **DOES NOT** modify code. It **PROVIDES INSTRUCTIONS** for a
-  single action at a time. You **MUST** apply the changes it suggests, and then run the tool
-  again to get the next step.
-* **Iterative Process:** The migration process is iterative. You must call this tool repeatedly,
-  applying the suggested fix after each call, until the tool indicates that no more actions are
-  needed.
-* **Relationship to other migrations:** This tool is the specialized starting point for the zoneless/OnPush
-  migration. For other migrations (like signal inputs), you should run the corresponding schematics first,
-  as the zoneless migration may depend on them as prerequisites.
-* **Input:** The tool can operate on either a single file or an entire directory. Provide the
-  absolute path.
+* This tool is strictly read-only and does NOT modify code. It outputs EXACTLY ONE actionable step at a time.
+* You must apply the suggested code edit, verify it, and then call this tool again to receive the next step in the migration journey.
+* Run modernization schematics (e.g., Signal Inputs migrations) as prerequisites before starting this migration.
+* Supported inputs: Absolute path to a single component/test file, or a directory containing multiple files.
 </Operational Notes>`,
   isReadOnly: true,
   isLocalOnly: true,
   inputSchema: {
     fileOrDirPath: z
       .string()
       .describe(
-        'The absolute path of the directory or file with the component(s), directive(s), or service(s) to migrate.' +
-          ' The contents are read with fs.readFileSync.',
+        'Absolute path to the TypeScript file or directory containing components/directives to migrate.',
       ),
   },
   factory:

packages/angular/cli/src/commands/mcp/tools/projects.ts

@@ -122,29 +122,20 @@ export const LIST_PROJECTS_TOOL = declareTool({
   title: 'List Angular Projects',
   description: `
 <Purpose>
-Provides a comprehensive overview of all Angular workspaces and projects within the repository.
-It is essential to use this tool as a first step before performing any project-specific actions to understand the available projects,
-their types, and their locations.
+Provides a comprehensive overview of all Angular workspaces, projects, and configured targets within the repository.
+Always use this tool as a mandatory first step before performing any project-specific actions
+to understand the available projects and locations.
 </Purpose>
 <Use Cases>
-* Finding the correct project name to use in other commands (e.g., \`ng generate component my-comp --project=my-app\`).
-* Identifying the \`root\` and \`sourceRoot\` of a project to read, analyze, or modify its files.
-* Determining a project's unit test framework (\`unitTestFramework\`) before writing or modifying tests.
-* Identifying the project's style language (\`styleLanguage\`) to use the correct file extension (e.g., \`.scss\`).
-* Getting the \`selectorPrefix\` for a project before generating a new component to ensure it follows conventions.
-* Identifying the major version of the Angular framework for each workspace, which is crucial for monorepos.
-* Determining a project's primary function by inspecting its builder (e.g., '@angular-devkit/build-angular:browser' for an application).
-* Identifying available architect targets (e.g., \`lint\`, \`e2e\`, \`serve\`, \`deploy\`) before attempting execution.
+* Discovering project names, locations, builders, selector prefixes, and style languages before generating or building components.
+* Determining a project's unit test framework (Jasmine, Jest, or Vitest) before writing or modifying tests.
+* Identifying available execution targets (e.g., lint, e2e, serve, deploy) before attempting execution.
+* Disambiguating multiple workspaces in monorepos.
 </Use Cases>
 <Operational Notes>
-* **Working Directory:** Shell commands for a project (like \`ng generate\`) **MUST**
-  be executed from the parent directory of the \`path\` field for the relevant workspace.
-* **Unit Testing:** The \`unitTestFramework\` field tells you which testing API to use (e.g., Jasmine, Jest).
-  If the value is 'unknown', you **MUST** inspect the project's configuration files
-  (e.g., \`karma.conf.js\`, \`jest.config.js\`, or the 'test' target in \`angular.json\`) to determine the
-  framework before generating tests.
-* **Disambiguation:** A monorepo may contain multiple workspaces (e.g., for different applications or even in output directories).
-  Use the \`path\` of each workspace to understand its context and choose the correct project.
+* Execute shell/CLI commands from the parent directory of the workspace's 'path' field.
+* If 'unitTestFramework' is 'unknown', inspect local config files (e.g., jest.config.js, karma.conf.js)
+  or the 'test' target in 'angular.json' to determine the framework before creating tests.
 </Operational Notes>`,
   outputSchema: listProjectsOutputSchema,
   isReadOnly: true,