@W-20397755@ [Scale products] Prompt cleanup + minor documentation changes (#396)

* added scale mcp init code

* added coverage to be above 95%

* added separate resource for adding fix instructions. added readme for devs

* removed redundant comment

* added SME aligned few shot prompts for antipatterns

* added parser based detection with tests

* added scale mcp init code

* feat: Add SOQL No WHERE/LIMIT clause antipattern detector

- Implemented AST-based detector for SOQL queries lacking WHERE or LIMIT clauses
- Added SOQLAstUtils for robust query extraction and analysis
- Created comprehensive fix instructions with severity levels and code examples
- Registered new detector in scan-apex-antipatterns-tool

* test: Add comprehensive test coverage for SOQL No WHERE/LIMIT antipattern

- Add unit tests for SOQLAstUtils (soql-ast-utils.test.ts)
- Add unit tests for SOQLNoWhereLimitDetector (soql-no-where-limit-detector.test.ts)
- Add unit tests for SOQLNoWhereLimitRecommender (soql-no-where-limit-recommender.test.ts)
- Cover edge cases: multi-line queries, nested subqueries, SOQL in loops, comments, complex WHERE clauses

* feat: add SOQL unused fields detector with AST-based analysis

* Added test cases

* consolidate SOQL utilities into soql-ast-utils.ts

* Minor change

* refactor: remove unused ast-analyzer.ts

- ast-analyzer.ts was not used anywhere in the codebase
- All AST operations are handled directly by @apexdevtools/apex-parser
- Reduces unnecessary code complexity

* style: minor cleanup changes

* added tool descriptions in README.md

* skipped flapping test for windows

* added runtime data enrichment

* added telemetry and removed redundant comments

* fixed tests

* fixed test failures

* added directory path and username params to lock active org to the right context.

* added dynamic api versioning

* removed implicit org assignment

* resolve windows errors

* added test coverage

* minor label changes according to CX feedback

* updates tests

* Adding validation for file extension to only allow apex files

* Minor prompt tweak for a feature enhancement

* Prompt enhancement for better CX

* updated README.md for scale toolset

* change state to GA

* tweaked readme to reflect all scale products

* documentation changes

* nit: documentation update

* Use backticks instead of string interpolation for a cleaner prompt.

* 1. Removed redundant severity legend
2. Removed a stray '\'

* Update Best Practices wording in README

---------

Co-authored-by: shuchita-singh <shuchita.singh@salesforce.com>
Co-authored-by: Willhoit <iowillhoit@users.noreply.github.com>

Author: 3 people

packages/mcp-provider-scale-products/README.md

@@ -78,12 +78,22 @@ To unlock **runtime-aware severity** powered by ApexGuru, the tool needs access
 
 | Level | Meaning |
 |---|---|
-| **Minor** | Low-impact issue; fix when convenient |
-| **Major** | Moderate performance risk; should be addressed |
-| **Critical** | High-impact hotspot; fix with priority |
+| **Minor** | Deviates from quality standards; fix when convenient |
+| **Major** | Reduces usability or causes a crucial part of your software to fail |
+| **Critical** | Highest priority; issues with run time, count, and other factors that result in software failure |
 
 When runtime metrics are available (org connected + ApexGuru enabled), severity is calculated from actual production execution data rather than static heuristics.
 
+## Best Practices
+
+If your MCP client isn't calling the Scale tools you expect, try these tips:
+
+1. **Scope tool execution.** Use the `--toolsets scale-products` argument in your MCP config files to improve tool resolution. Too many registered tools make it difficult for your MCP host to resolve the correct one. Disable any tools you don't actively use.
+
+2. **Reference tools explicitly.** Reference the tool by name in your prompt so the LLM knows exactly which tool to invoke. For example:
+
+   > *Scan MyClass.cls for performance antipatterns using the `scan_apex_class_for_antipatterns` MCP tool.*
+
 ## Development
 
 Ensure you are in the monorepo root or the package directory.

packages/mcp-provider-scale-products/src/tools/scan-apex-antipatterns-tool.ts

@@ -118,30 +118,16 @@ export class ScanApexAntipatternsTool extends McpTool<InputArgsShape, OutputArgs
   public getConfig(): McpToolConfig<InputArgsShape, OutputArgsShape> {
     return {
       title: "Scan Apex Class for Antipatterns",
-      description:
-        "Apex Code Scan Tool: Invoke (alongside other code scan tools if needed) whenever the user intends to scan or analyze an Apex class. " +
-        "Analyzes an Apex class file for performance antipatterns and provides " +
-        "recommendations for fixing them. Currently detects: " +
-        "1) Schema.getGlobalDescribe() usage with optimized alternatives " +
-        "2) SOQL queries without WHERE or LIMIT clauses " +
-        "3) SOQL queries with unused fields (with fix generation). " +
-        "Distinguishes between different severity levels (e.g., usage in loops vs. ordinary usage). " +
-        "When authenticated to an org with ApexGuru enabled, severity is calculated from actual runtime metrics. " +
-        "IMPORTANT: If the user does not mention an org alias or username in the request, call #get_username tool to  resolve the default org username. " +
-        "Requires an absolute path to the Apex class file. " +
-        "\n" +
-        "==== PRESENTATION INSTRUCTIONS ====" +
-        "\n1. ALWAYS start with a clear header indicating whether runtime analysis from production org was used:" +
-        "   - If runtime metrics were used: '🔬 LEVERAGING YOUR ORG'S RUNTIME INTELLIGENCE VIA APEXGURU: Analyzing with Production Metrics from [OrgId]'" +
-        "\n2. Display this LEGEND prominently at the beginning of your response:" +
-        "   ╔════════════════════════════════════════════════════════╗\n" +
-        "   ║                        SEVERITY LEGEND                ║\n" +
-        "   ╠════════════════════════════════════════════════════════╣\n" +
-        "   ║   🟡 = Minor Severity Antipattern                     ║\n" +
-        "   ║   🟠 = Major Severity Antipattern                     ║\n" +
-        "   ║   🔴 = Critical Severity Antipattern                  ║\n" +
-        "   ║   💡 = Severity from Production Metrics               ║\n" +
-        "   ╚════════════════════════════════════════════════════════╝\n",
+      description: `Apex Code Scan Tool: Invoke (alongside other code scan tools if needed) whenever the user intends to scan or analyze an Apex class.
+Analyzes an Apex class file for performance antipatterns and provides recommendations for fixing them. Currently detects:
+1) Schema.getGlobalDescribe() usage with optimized alternatives
+2) SOQL queries without WHERE or LIMIT clauses
+3) SOQL queries with unused fields (with fix generation).
+Distinguishes between different severity levels (e.g., usage in loops vs. ordinary usage).
+When authenticated to an org with ApexGuru enabled, severity is calculated from actual runtime metrics.
+IMPORTANT: If the user does not mention an org alias or username in the request, call #get_username tool to resolve the default org username.
+Requires an absolute path to the Apex class file.
+`,
       inputSchema: scanApexInputSchema.shape,
       outputSchema: undefined,
       annotations: {
@@ -449,51 +435,57 @@ export class ScanApexAntipatternsTool extends McpTool<InputArgsShape, OutputArgs
       0
     );
 
-    let response = "";
-
-    // Add header based on runtime analysis status
-    if (runtimeDataStatus === RuntimeDataStatus.SUCCESS) {
-      response += `# 🔬 Leveraging Your Org's Runtime Intelligence via ApexGuru\n\n`;
-    } 
-    // Add severity legend
-    response += `╔════════════════════════════════════════════════════════╗\n`;
-    response += `║                        SEVERITY LEGEND                ║\n`;
-    response += `╠════════════════════════════════════════════════════════╣\n`;
-    response += `║   🟡 = Minor Severity Antipattern                     ║\n`;
-    response += `║   🟠 = Major Severity Antipattern                     ║\n`;
-    response += `║   🔴 = Critical Severity Antipattern                  ║\n`;
-    response += `║   💡 = Severity from Production Metrics               ║\n`;
-    response += `╚════════════════════════════════════════════════════════╝\n\n`;
-
-    response += `## Antipattern Scan Results for '${className}'\n\n`;
-    response += `Found ${totalIssues} issue(s) across ${scanResult.antipatternResults.length} antipattern type(s).\n`;
-
-    response += this.getRuntimeDataMessage(runtimeDataStatus);
-    response += `\n`;
-
-    response += `## Scan Results\n\n`;
-    response += "Results are grouped by antipattern type. Each type has:\n";
-    response += "- **fixInstruction**: How to fix this antipattern type (applies to all instances)\n";
-    response += "- **detectedInstances**: All detected instances of this type\n\n";
-
-    // Transform results to add bulb icon for runtime-derived severity
+    const runtimeHeader = runtimeDataStatus === RuntimeDataStatus.SUCCESS
+      ? `# 🔬 Maximizing Organizational Runtime Intelligence with ApexGuru\n\n`
+      : "";
+
     const displayResult = this.addSeverityIcons(scanResult);
 
-    response += "```json\n";
-    response += JSON.stringify(displayResult, null, 2);
-    response += "\n```\n\n";
-
-    response += `## Instructions for Code Fixes\n\n`;
-    response += `When applying fixes in code, include the following in comments:\n`;
-    response += `- For each antipattern, include the appropriate severity dot (🟡/🟠/🔴)\n`;
-    response += `- Add 💡 next to severity dot when runtime metrics were used to calculate severity\n\n`;
-    response += `The scan result contains multiple antipattern types. For each type:\n`;
-    response += `1. Read the \`fixInstruction\` - this explains how to fix this antipattern\n`;
-    response += `2. For each instance in \`detectedInstances\`:\n`;
-    response += `   - Examine \`codeBefore\` (the problematic code)\n`;
-    response += `   - Consider \`severity\` (critical/major/minor)\n`;
-    response += `   - Generate the fixed code following the instruction\n\n`;
-    response += `Generate fixes for all detected instances across all antipattern types.\n`;
+    const response = `==== PRESENTATION INSTRUCTIONS ====
+1. ALWAYS start with a clear header indicating whether runtime analysis from production org was used:
+   - If runtime metrics were used: '🔬 Analyzing with Production Metrics from [OrgId]'
+   - Otherwise: do not use the runtime header.
+2. Display the SEVERITY LEGEND prominently at the beginning of your response.
+
+${runtimeHeader}
+**SEVERITY LEGEND**
+- 🟡 Minor: Deviates from quality standards
+- 🟠 Major: Reduces usability or causes failure
+- 🔴 Critical: Highest priority, causes failure
+- 💡 Severity from Production Metrics
+
+**Presentation:** Be concise, conversational, direct, and positive. Address the reader as "you." Use a casual tone but avoid jargon and slang. Avoid "please" and "sorry"; use exclamation points sparingly. Design text for easy scanning.
+
+## Antipattern Scan Results for '${className}'
+
+Found ${totalIssues} issue(s) across ${scanResult.antipatternResults.length} antipattern type(s).
+${this.getRuntimeDataMessage(runtimeDataStatus)}
+
+## Scan Results
+
+Results are grouped by antipattern type. Each type has:
+- **fixInstruction**: How to fix this antipattern type (applies to all instances)
+- **detectedInstances**: All detected instances of this type
+
+\`\`\`json
+${JSON.stringify(displayResult, null, 2)}
+\`\`\`
+
+## Instructions for Code Fixes
+
+When applying fixes in code, include the following in comments:
+- For each antipattern, include the appropriate severity dot (🟡/🟠/🔴)
+- Add 💡 next to severity dot when runtime metrics were used to calculate severity
+
+The scan result contains multiple antipattern types. For each type:
+1. Read the \`fixInstruction\` - this explains how to fix this antipattern
+2. For each instance in \`detectedInstances\`:
+   - Examine \`codeBefore\` (the problematic code)
+   - Consider \`severity\` (critical/major/minor)
+   - Generate the fixed code following the instruction
+
+Generate fixes for all detected instances across all antipattern types.
+`;
 
     return response;
   }