fix(mcp): improve metadata download UX and secrets field descriptions

Three issues observed in the field:

1. provar.automation.metadata.download had a sparse description with no
   mention of config.load as a prerequisite or how to use the -c flag.
   Updated description to call out PREREQUISITE, correct flags usage
   (["-c", "Name1,Name2"]), and that [DOWNLOAD_ERROR] means auth failure.

2. When [DOWNLOAD_ERROR] appears in the error output (95% of the time an
   expired/wrong credential for the connection), the response now includes
   a details.suggestion field with actionable steps: check .secrets
   credentials, connection name spelling, scratch org expiry, and that
   testprojectSecrets is an encryption key not a file path.

3. testprojectSecrets in propertiesTools.ts and secrets_password in
   antTools.ts had descriptions easily misread as file paths. Both now
   explicitly say "encryption key string, not a file path".

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mrdailey99

src/mcp/tools/antTools.ts

@@ -192,7 +192,7 @@ export function registerAntGenerate(server: McpServer, config: ServerConfig): vo
         .string()
         .default('${env.ProvarSecretsPassword}')
         .describe(
-          'Password for the Provar secrets store. Defaults to reading from the ProvarSecretsPassword environment variable.'
+          'Encryption key used to decrypt the Provar .secrets file (the password string itself, not a file path). Defaults to reading from the ProvarSecretsPassword environment variable.'
         ),
       test_environment_secrets_password: z
         .string()

src/mcp/tools/automationTools.ts

@@ -233,12 +233,29 @@ export function registerAutomationCompile(server: McpServer): void {
 
 // ── Tool: provar.automation.metadata.download ─────────────────────────────────
 
+const DOWNLOAD_ERROR_SUGGESTION =
+  'A [DOWNLOAD_ERROR] almost always means a Salesforce authentication failure for the connection being used. ' +
+  'Check: (1) the connection credentials in the Provar project .secrets file are current and not expired; ' +
+  '(2) the named connection exists in the project and the name is spelled correctly (case-sensitive); ' +
+  '(3) if using a scratch org, confirm it has not expired (`sf org list`); ' +
+  '(4) if testprojectSecrets is set in provardx-properties.json, it must be the encryption key string used to decrypt .secrets — not a file path.';
+
 export function registerAutomationMetadataDownload(server: McpServer): void {
   server.tool(
     'provar.automation.metadata.download',
-    'Download Salesforce metadata into a Provar project. Invokes `sf provar automation metadata download`.',
+    [
+      'Download Salesforce metadata for one or more connections into a Provar project.',
+      'Invokes `sf provar automation metadata download`.',
+      'PREREQUISITE: Call provar.automation.config.load first — without it the command fails with MISSING_FILE.',
+      'Use the -c flag to specify connections: flags: ["-c", "ConnectionName1,ConnectionName2"].',
+      'Connection names are case-sensitive and must match the names defined in the Provar project.',
+      'If the download fails with [DOWNLOAD_ERROR], this is almost always a Salesforce authentication issue —',
+      'check that the credentials in the project .secrets file are current and that any referenced scratch orgs have not expired.',
+    ].join(' '),
     {
-      flags: z.array(z.string()).optional().default([]).describe('Raw CLI flags to forward (e.g. ["--target-org", "myorg"])'),
+      flags: z.array(z.string()).optional().default([]).describe(
+        'Raw CLI flags to forward. Use ["-c", "Name1,Name2"] to specify connections (required). Example: ["-c", "MyOrg,SandboxOrg"]'
+      ),
       sf_path: z.string().optional().describe('Path to the sf CLI executable when not in PATH (e.g. "~/.nvm/versions/node/v22.0.0/bin/sf")'),
     },
     ({ flags, sf_path }) => {
@@ -247,12 +264,15 @@ export function registerAutomationMetadataDownload(server: McpServer): void {
 
       try {
         const result = runSfCommand(['provar', 'automation', 'metadata', 'download', ...flags], sf_path);
-        const response = { requestId, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
+        const message = result.stderr || result.stdout;
 
         if (result.exitCode !== 0) {
-          return { isError: true as const, content: [{ type: 'text' as const, text: JSON.stringify(makeError('AUTOMATION_METADATA_FAILED', result.stderr || result.stdout, requestId)) }] };
+          const isDownloadError = message.includes('[DOWNLOAD_ERROR]');
+          const details: Record<string, unknown> = isDownloadError ? { suggestion: DOWNLOAD_ERROR_SUGGESTION } : {};
+          return { isError: true as const, content: [{ type: 'text' as const, text: JSON.stringify(makeError('AUTOMATION_METADATA_FAILED', message, requestId, false, details)) }] };
         }
 
+        const response = { requestId, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
         return { content: [{ type: 'text' as const, text: JSON.stringify(response) }], structuredContent: response };
       } catch (err) {
         return handleSpawnError(err, requestId, 'provar.automation.metadata.download');

src/mcp/tools/propertiesTools.ts

@@ -224,7 +224,10 @@ const updatesSchema = z.object({
   pluginOutputlevel: z.enum(['SEVERE', 'WARNING', 'INFO', 'FINE', 'FINER', 'FINEST']).optional().describe('Amount of plugin output logged'),
   stopOnError: z.boolean().optional().describe('Abort test run on first failure'),
   excludeCallable: z.boolean().optional().describe('Omit callable test cases from execution'),
-  testprojectSecrets: z.string().optional().describe('Test project secrets encryption password'),
+  testprojectSecrets: z.string().optional().describe(
+    'Encryption key (password string) used to decrypt the .secrets file in the Provar project root. ' +
+    'This is the key itself — NOT a file path. Leave empty if your project does not use secrets encryption.'
+  ),
   environment: z.object({
     testEnvironment: z.string().optional().describe('Name of the test environment to run against'),
     webBrowser: z.enum(['Chrome', 'Safari', 'Edge', 'Edge_Legacy', 'Firefox', 'IE', 'Chrome_Headless']).optional(),

test/unit/mcp/automationTools.test.ts

@@ -422,6 +422,23 @@ describe('automationTools', () => {
       const result = server.call('provar.automation.metadata.download', { flags: [] });
       assert.equal(parseBody(result).error_code, 'SF_NOT_FOUND');
     });
+
+    it('includes suggestion in details when [DOWNLOAD_ERROR] is in the message', () => {
+      spawnStub.returns(makeSpawnResult('', 'Error (1): [DOWNLOAD_ERROR] ERROR\n', 1));
+      const result = server.call('provar.automation.metadata.download', { flags: ['-c', 'MyOrg'] });
+      assert.ok(isError(result));
+      const body = parseBody(result);
+      assert.equal(body.error_code, 'AUTOMATION_METADATA_FAILED');
+      assert.ok(body.details && typeof (body.details as Record<string, unknown>).suggestion === 'string', 'Expected suggestion in details for DOWNLOAD_ERROR');
+    });
+
+    it('does NOT include suggestion for other failure messages', () => {
+      spawnStub.returns(makeSpawnResult('', 'Error (2): Nonexistent flag: --properties-file\n', 1));
+      const result = server.call('provar.automation.metadata.download', { flags: [] });
+      assert.ok(isError(result));
+      const body = parseBody(result);
+      assert.ok(!body.details || !(body.details as Record<string, unknown>).suggestion, 'Expected no suggestion for non-DOWNLOAD_ERROR');
+    });
   });
 
   // ── provar.automation.config.load ─────────────────────────────────────────