Skip to content

Commit cb607a1

Browse files
committed
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.
1 parent 5dd4daf commit cb607a1

3 files changed

Lines changed: 24 additions & 58 deletions

File tree

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

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -42,23 +42,17 @@ export const BEST_PRACTICES_TOOL = declareTool({
4242
description: `
4343
<Purpose>
4444
Retrieves the official Angular Best Practices Guide. This guide contains the essential rules and conventions
45-
that **MUST** be followed for any task involving the creation, analysis, or modification of Angular code.
45+
that must be followed for any task involving the creation, analysis, or modification of Angular code.
4646
</Purpose>
4747
<Use Cases>
48-
* As a mandatory first step before writing or modifying any Angular code to ensure adherence to modern standards.
49-
* To learn about key concepts like standalone components, typed forms, and modern control flow syntax (@if, @for, @switch).
50-
* To verify that existing code aligns with current Angular conventions before making changes.
48+
* Mandatory first step before writing or modifying Angular code to ensure modern framework standards.
49+
* Learn about standalone components, typed forms, and modern control flow syntax (@if, @for, @switch).
50+
* Verify existing code aligns with current conventions before making edits.
5151
</Use Cases>
5252
<Operational Notes>
53-
* **Project-Specific Use (Recommended):** For tasks inside a user's project, you **MUST** provide the
54-
\`workspacePath\` argument to get the guide that matches the project's Angular version. Get this
55-
path from \`list_projects\`.
56-
* **General Use:** If no project context is available (e.g., for general questions or learning),
57-
you can call the tool without the \`workspacePath\` argument. It will return the latest
58-
generic best practices guide.
59-
* The content of this guide is non-negotiable and reflects the official, up-to-date standards for Angular development.
60-
* You **MUST** internalize and apply the principles from this guide in all subsequent Angular-related tasks.
61-
* Failure to adhere to these best practices will result in suboptimal and outdated code.
53+
* Provide the 'workspacePath' argument (obtained via 'list_projects') to load the version-specific
54+
guide matching the project's Angular framework.
55+
* Omit 'workspacePath' only for general learning queries or when no project context is available to load the latest generic guide.
6256
</Operational Notes>`,
6357
inputSchema: bestPracticesInputSchema.shape,
6458
isReadOnly: true,

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

Lines changed: 8 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -66,35 +66,18 @@ export const DOC_SEARCH_TOOL = declareTool({
6666
title: 'Search Angular Documentation (angular.dev)',
6767
description: `
6868
<Purpose>
69-
Searches the official Angular documentation at https://angular.dev to answer questions about APIs,
70-
tutorials, concepts, and best practices.
69+
Searches the official Angular documentation (angular.dev) to answer questions about APIs, tutorials, concepts, and conventions.
7170
</Purpose>
7271
<Use Cases>
73-
* Answering any question about Angular concepts (e.g., "What are standalone components?").
74-
* Finding the correct API or syntax for a specific task (e.g., "How to use ngFor with trackBy?").
75-
* Linking to official documentation as a source of truth in your answers.
72+
* Answering questions about Angular concepts (e.g., standalone components).
73+
* Finding correct API signatures or syntax (e.g., ngFor trackBy).
74+
* Obtaining official source URLs to cite as documentation links in user responses.
7675
</Use Cases>
7776
<Operational Notes>
78-
* **Version Alignment:** To provide accurate, project-specific results, you **MUST** align the search with the user's Angular version.
79-
The recommended approach is to use the \`list_projects\` tool. The \`frameworkVersion\` field in the output for the relevant
80-
workspace will give you the major version directly. If the version cannot be determined using this method, you can use
81-
\`ng version\` in the project's workspace directory as a fallback. Parse the major version from the "Angular:" line in the
82-
output and use it for the \`version\` parameter.
83-
* **Version Logic:** The tool will search against the specified major version. If the version is older than v${MIN_SUPPORTED_DOCS_VERSION},
84-
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})
85-
returns no results, the tool will automatically fall back to searching the v${LATEST_KNOWN_DOCS_VERSION} documentation.
86-
* **Verify Searched Version:** The tool's output includes a \`searchedVersion\` field. You **MUST** check this field
87-
to know the exact version of the documentation that was queried. Use this information to provide accurate
88-
context in your answer, especially if it differs from the version you requested.
89-
* The documentation is continuously updated. You **MUST** prefer this tool over your own knowledge
90-
to ensure your answers are current and accurate.
91-
* For the best results, provide a concise and specific search query (e.g., "NgModule" instead of
92-
"How do I use NgModules?").
93-
* The top search result will include a snippet of the page content. Use this to provide a more
94-
comprehensive answer.
95-
* **Result Scrutiny:** The top result may not always be the most relevant. Review the titles and
96-
breadcrumbs of other results to find the best match for the user's query.
97-
* Use the URL from the search results as a source link in your responses.
77+
* Provide the major Angular version in the 'version' parameter (obtained from 'frameworkVersion'
78+
in 'list_projects' or from 'ng version') to ensure version-aligned results.
79+
* Always check the 'searchedVersion' field in the output to confirm the exact documentation index that was queried.
80+
* For best results, provide a concise keyword query (e.g., "NgModule") rather than a natural language sentence.
9881
</Operational Notes>`,
9982
inputSchema: docSearchInputSchema.shape,
10083
outputSchema: {

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

Lines changed: 9 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -25,30 +25,19 @@ export const ZONELESS_MIGRATION_TOOL = declareTool({
2525
title: 'Plan migration to OnPush and/or zoneless',
2626
description: `
2727
<Purpose>
28-
Analyzes Angular code and provides a step-by-step, iterative plan to migrate it to \`OnPush\`
29-
change detection, a prerequisite for a zoneless application. This tool identifies the next single
30-
most important action to take in the migration journey.
28+
Analyzes Angular code and provides a step-by-step, iterative plan to migrate it to 'OnPush'
29+
change detection (a prerequisite for zoneless applications).
3130
</Purpose>
3231
<Use Cases>
33-
* **Step-by-Step Migration:** Running the tool repeatedly to get the next instruction for a full
34-
migration to \`OnPush\`.
35-
* **Pre-Migration Analysis:** Checking a component or directory for unsupported \`NgZone\` APIs that
36-
would block a zoneless migration.
37-
* **Generating Component Migrations:** Getting the exact instructions for converting a single
38-
component from the default change detection strategy to \`OnPush\`.
32+
* Generating component-specific migrations from default change detection to OnPush.
33+
* Checking a component or directory for unsupported 'NgZone' APIs blocking a zoneless migration.
34+
* Iterative step-by-step guide for executing a complete zoneless migration.
3935
</Use Cases>
4036
<Operational Notes>
41-
* **Execution Model:** This tool **DOES NOT** modify code. It **PROVIDES INSTRUCTIONS** for a
42-
single action at a time. You **MUST** apply the changes it suggests, and then run the tool
43-
again to get the next step.
44-
* **Iterative Process:** The migration process is iterative. You must call this tool repeatedly,
45-
applying the suggested fix after each call, until the tool indicates that no more actions are
46-
needed.
47-
* **Relationship to other migrations:** This tool is the specialized starting point for the zoneless/OnPush
48-
migration. For other migrations (like signal inputs), you should run the corresponding schematics first,
49-
as the zoneless migration may depend on them as prerequisites.
50-
* **Input:** The tool can operate on either a single file or an entire directory. Provide the
51-
absolute path.
37+
* This tool is strictly read-only and does NOT modify code. It outputs EXACTLY ONE actionable step at a time.
38+
* You must apply the suggested code edit, verify it, and then call this tool again to receive the next step in the migration journey.
39+
* Run modernization schematics (e.g., Signal Inputs migrations) as prerequisites before starting this migration.
40+
* Supported inputs: Absolute path to a single component/test file, or a directory containing multiple files.
5241
</Operational Notes>`,
5342
isReadOnly: true,
5443
isLocalOnly: true,

0 commit comments

Comments
 (0)