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

Refactor the descriptions of get_best_practices, search_documentation, and onpush_zoneless_migration tools to improve semantic clarity and reduce system prompt token footprints. Remove redundant operational boilerplate, eliminate internal server logic leakage related to version clamping, and consolidate overlapping iterative process instructions.

Author: clydin

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

@@ -119,28 +119,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).
+* 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,