fix: improve sf-get-username instructions W-19472383 (#181)

* fix: improve sf-get-username instructions

* chore(release): mcp-provider-dx-core@0.2.2 [skip ci]

* chore: bump @salesforce/mcp-provider-dx-core to 0.2.2 --no-verify

Auto-update dependency after provider package publish.

Related release: mcp-provider-dx-core@0.2.2

* chore(release): 0.19.1-dev.0 [skip ci]

---------

Co-authored-by: svc-cli-bot <Svc_cli_bot@salesforce.com>

Author: cristiand391

packages/mcp-provider-dx-core/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [0.2.2](https://github.com/salesforcecli/mcp/compare/mcp-provider-dx-core@0.2.1...mcp-provider-dx-core@0.2.2) (2025-09-02)
+
+
+### Bug Fixes
+
+* improve sf-get-username instructions ([2c5a63f](https://github.com/salesforcecli/mcp/commit/2c5a63f541108fcae0dbd2f5620c7279b616bb26))
+
+
+
 ## [0.2.1](https://github.com/salesforcecli/mcp/compare/mcp-provider-dx-core@0.2.0...mcp-provider-dx-core@0.2.1) (2025-08-29)
 
 

packages/mcp-provider-dx-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/mcp-provider-dx-core",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "MCP provider for core Salesforce DX functionality",
   "types": "lib/index.d.ts",
   "license": "Apache-2.0",

packages/mcp-provider-dx-core/src/shared/params.ts

@@ -24,17 +24,13 @@ import { sanitizePath } from './utils.js';
 export const usernameOrAliasParam = z.string()
   .describe(`The username or alias for the Salesforce org to run this tool against.
 
-AGENT INSTRUCTIONS:
-If it is not clear what username or alias is, run the #sf-get-username tool.
-NEVER guess or make-up a username or alias, use #sf-get-username if you are not sure.
-DO NOT use #sf-get-username if the user mentions an alias or username, like "for my an-alias org" or "for my test-prgelc2petd9@example.com org".
-
-USAGE:
-...for the my-alias org
-...for my 'my-alias' user
-...for alias myAlias
-...for my 'test@example.com' user
-...for the 'test@example.com' org`);
+A username follows the <name@domain.com> format.
+If the user refers to an org with a string not following that format, it can be a valid alias.
+
+IMPORTANT:
+- If it is not clear what the username or alias is, run the #sf-get-username tool to resolve it.
+- NEVER guess or make-up a username or alias.
+`);
 
 export const useToolingApiParam = z.boolean().optional().describe('Use Tooling API for the operation');
 

packages/mcp-provider-dx-core/src/tools/sf-get-username.ts

@@ -78,23 +78,8 @@ export async function suggestUsername(orgService: OrgService): Promise<{
  */
 
 export const getUsernameParamsSchema = z.object({
-  defaultTargetOrg: z.boolean().optional().default(false).describe(`Try to find default org
-AGENT INSTRUCTIONS:
-ONLY SET TO TRUE when the user explicitly asks for the default org or default target org.
-Leave it as false when the user is vague and says something like "for my org" or "for my-alias".
-
-USAGE EXAMPLE:
-Get username for my default org
-...for my default target org`),
-  defaultDevHub: z.boolean().optional().default(false).describe(`Try to find default dev hub
-AGENT INSTRUCTIONS:
-ONLY SET TO TRUE when the user explicitly asks for the default dev hub or default target devhub.
-Leave it as false when the user is vague and says something like "for my org" or "for my-alias".
-
-USAGE EXAMPLE:
-Get username for my default dev hub
-...for my default target dev hub
-...for my default devhub`),
+  defaultTargetOrg: z.boolean().optional().default(false).describe('Resolve the default target org username'),
+  defaultDevHub: z.boolean().optional().default(false).describe('Resolve the default target devhub org username'),
   directory: directoryParam,
 });
 
@@ -124,23 +109,13 @@ export class GetUsernameMcpTool extends McpTool<InputArgsShape, OutputArgsShape>
       title: 'Get Username',
       description: `Intelligently determines the appropriate username or alias for Salesforce operations.
 
-AGENT/LLM INSTRUCTIONS:
-Use this tool when uncertain which username/org a user wants for Salesforce operations.
-This tool handles three distinct scenarios:
+WHEN TO USE THIS TOOL:
+- When uncertain which org username a user wants for Salesforce operations.
 
-1. When defaultTargetOrg=true: Fetches the default target org configuration
-   - Use when user says "for my default org" or "for my default target org"
-
-2. When defaultDevHub=true: Fetches the default dev hub configuration
-   - Use when user says "for my default dev hub" or "for my default target dev hub"
-
-3. When both are false (default): Uses suggestUsername to intelligently determine the appropriate org
-   - Use when user is vague and says something like "for my org" or doesn't specify
-
-EXAMPLE USAGE:
-- When user says "Do X for my org" → defaultTargetOrg=false, defaultDevHub=false
-- When user says "For my default org" → defaultTargetOrg=true
-- When user says "For my default dev hub" → defaultDevHub=true`,
+To resolve the default org username, set the defaultTargetOrg param to true and defaultDevHub to false.
+To resole the default devhub org username, set the defaultTargetOrg param to false and defaultDevHub to true.
+If it's not clear which type of org to resolve, set both defaultTargetOrg and defaultDevHub to false to an allow-listed org username available.
+`,
       inputSchema: getUsernameParamsSchema.shape,
       outputSchema: undefined,
       annotations: {

packages/mcp/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [0.19.1-dev.0](https://github.com/salesforcecli/mcp/compare/0.19.0...0.19.1-dev.0) (2025-09-02)
+
+
+
 # [0.19.0](https://github.com/salesforcecli/mcp/compare/0.18.0...0.19.0) (2025-08-29)
 
 

packages/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/mcp",
-  "version": "0.19.0",
+  "version": "0.19.1-dev.0",
   "description": "MCP Server for interacting with Salesforce instances",
   "bin": {
     "sf-mcp-server": "bin/run.js"
@@ -48,7 +48,7 @@
     "@salesforce/core": "^8.18.0",
     "@salesforce/kit": "^3.1.6",
     "@salesforce/mcp-provider-api": "0.2.0",
-    "@salesforce/mcp-provider-dx-core": "0.2.1",
+    "@salesforce/mcp-provider-dx-core": "0.2.2",
     "@salesforce/mcp-provider-code-analyzer": "0.0.2",
     "@salesforce/source-deploy-retrieve": "^12.22.0",
     "@salesforce/source-tracking": "^7.4.8",