feat: inherit MCP descriptions from CLI help

Author: thymikee

src/commands/__tests__/command-surface-metadata.test.ts

@@ -41,6 +41,21 @@ test('CI-only prepare command stays out of MCP tool surface', () => {
   assert.equal(listMcpExposedCommandNames().includes('prepare'), false);
 });
 
+test('MCP tool descriptions inherit complete CLI guidance', () => {
+  const cliSchemas = listCommandFamilyCliSchemas();
+  const definitionsByName = new Map(
+    listCommandFamilyDefinitions().map((definition) => [definition.name, definition] as const),
+  );
+
+  for (const metadata of listMcpCommandMetadata()) {
+    const cliSchema = cliSchemas[metadata.name];
+    const cliDescription = cliSchema?.helpDescription ?? cliSchema?.summary;
+    assert.ok(cliDescription, `${metadata.name} must define CLI guidance for its MCP description`);
+    assert.equal(metadata.description, cliDescription);
+    assert.equal(definitionsByName.get(metadata.name)?.description, cliDescription);
+  }
+});
+
 test('common command input accepts web platform selector', () => {
   const snapshotMetadata = listCommandMetadata().find((metadata) => metadata.name === 'snapshot');
   if (!snapshotMetadata) throw new Error('Expected snapshot command metadata');

src/commands/capture/alert.ts

@@ -34,6 +34,8 @@ const alertCommandDefinition = defineExecutableCommand(alertCommandMetadata, (cl
 
 const alertCliSchema = {
   usageOverride: 'alert [get|accept|dismiss|wait] [timeout]',
+  helpDescription:
+    'Inspect, wait for, accept, or dismiss a platform alert. Use get before acting when the alert content matters; accept and dismiss change the active alert state.',
   positionalArgs: ['action?', 'timeout?'],
 } as const;
 

src/commands/capture/wait.ts

@@ -49,6 +49,8 @@ const waitCommandDefinition = defineExecutableCommand(waitCommandMetadata, (clie
 
 const waitCliSchema = {
   usageOverride: 'wait <ms>|text <text>|@ref|<selector>|stable [quietMs] [timeoutMs]',
+  helpDescription:
+    'Wait for a duration, text, snapshot ref, selector, or stable UI. Use text, ref, or selector for a specific readiness condition; stable waits until the UI stays quiet for the requested window.',
   positionalArgs: ['durationOrSelector', 'timeoutMs?'],
   allowsExtraPositionals: true,
   allowedFlags: [...SELECTOR_SNAPSHOT_FLAGS],

src/commands/family/types.ts

@@ -62,7 +62,16 @@ export function defineCommandFacet<
   const TCommandName extends string,
   const TCommand extends CommandFacet<TCommandName>,
 >(command: TCommand): TCommand {
-  return command;
+  const description = command.cliSchema?.helpDescription ?? command.cliSchema?.summary;
+  if (!description) return command;
+
+  // CLI help is the command-surface owner for agent-facing guidance. Keep MCP
+  // tool descriptions aligned by default so the two projections cannot drift.
+  return {
+    ...command,
+    metadata: { ...command.metadata, description },
+    definition: { ...command.definition, description },
+  } as TCommand;
 }
 
 export function defineCommandFamilyFromFacets<

src/commands/interaction/index.ts

@@ -61,6 +61,8 @@ import { selectorCliReaders, selectorDaemonWriters } from './selectors.ts';
 const interactionCliSchemas = {
   get: {
     usageOverride: 'get text|attrs <@ref|selector>',
+    helpDescription:
+      'Read text or accessibility attributes from a snapshot ref or selector without changing the app. Use format text for visible content or attrs for the element attribute map.',
     positionalArgs: ['subcommand', 'target'],
     allowsExtraPositionals: true,
     allowedFlags: [...SELECTOR_SNAPSHOT_FLAGS, 'record'],
@@ -74,12 +76,16 @@ const interactionCliSchemas = {
     allowedFlags: ['snapshotDepth', 'snapshotRaw', 'findFirst', 'findLast', 'record'],
   },
   is: {
+    helpDescription:
+      'Check whether a selector satisfies a UI predicate such as visible, hidden, editable, selected, focused, or text. Use wait when the condition may appear asynchronously.',
     positionalArgs: ['predicate', 'selector', 'value?'],
     allowsExtraPositionals: true,
     allowedFlags: [...SELECTOR_SNAPSHOT_FLAGS, 'record'],
   },
   click: {
     usageOverride: 'click <x y|@ref|selector>',
+    helpDescription:
+      'Activate a UI target by snapshot ref, selector, or coordinates. Prefer a ref or selector after snapshot; use coordinates only when semantic targeting is unavailable. This can change app state; use settle or snapshot to verify the result.',
     positionalArgs: ['target'],
     allowsExtraPositionals: true,
     allowedFlags: [
@@ -128,15 +134,21 @@ const interactionCliSchemas = {
     allowedFlags: ['pointerCount'],
   },
   focus: {
+    helpDescription:
+      'Move input focus to explicit screen coordinates without entering text. Prefer semantic interactions when a snapshot ref or selector is available; use type or fill after focus.',
     positionalArgs: ['x', 'y'],
   },
   type: {
+    helpDescription:
+      'Append text to the currently focused input. Use fill when the existing field value should be replaced, and focus first when no input is active.',
     positionalArgs: ['text'],
     allowsExtraPositionals: true,
     allowedFlags: ['delayMs'],
   },
   fill: {
     usageOverride: 'fill <x> <y> <text> | fill <@ref|selector> <text>',
+    helpDescription:
+      'Replace text in a UI input selected by snapshot ref, selector, or coordinates. Prefer refs or selectors after snapshot; use recordAs to keep sensitive text out of a recorded replay while sending it to the live app.',
     positionalArgs: ['targetOrX', 'yOrText', 'text?'],
     allowsExtraPositionals: true,
     allowedFlags: [

src/commands/management/app.ts

@@ -128,6 +128,8 @@ const openCliSchema = {
 } as const satisfies CommandSchemaOverride;
 
 const closeCliSchema = {
+  helpDescription:
+    'Close the named app, or close the active session app when app is omitted. Use shutdown only when the selected simulator or emulator should also stop.',
   positionalArgs: ['app?'],
   allowedFlags: ['saveScript', 'force', 'shutdown'],
 } as const satisfies CommandSchemaOverride;

src/commands/management/device.ts

@@ -53,6 +53,11 @@ const bootCliSchema = {
   allowedFlags: ['headless'],
 } as const satisfies CommandSchemaOverride;
 
+const devicesCliSchema = {
+  helpDescription:
+    'List available devices and simulators that can be selected for automation. Use platform, device, udid, or serial inputs on later commands to target one result.',
+} as const satisfies CommandSchemaOverride;
+
 const capabilitiesCliSchema = {
   summary: 'List supported commands for the selected device',
   helpDescription:
@@ -79,6 +84,7 @@ const devicesCommandFacet = defineCommandFacet({
   name: 'devices',
   metadata: devicesCommandMetadata,
   definition: devicesCommandDefinition,
+  cliSchema: devicesCliSchema,
   cliReader: commonCliReader,
   daemonWriter: devicesDaemonWriter,
   cliOutputFormatter: managementCliOutputFormatters.devices,

src/commands/management/install.ts

@@ -68,10 +68,14 @@ const installFromSourceCommandDefinition = defineExecutableCommand(
 const installCliSchema = {
   usageOverride: 'install <path> | install <app> <path>',
   listUsageOverride: 'install <path>',
+  helpDescription:
+    'Install an app binary from a local path. Provide an app identifier with the path when the target needs explicit app selection; use reinstall to replace an already installed app.',
   positionalArgs: ['appOrPath', 'path?'],
 } as const satisfies CommandSchemaOverride;
 
 const reinstallCliSchema = {
+  helpDescription:
+    'Replace an installed app with a binary from a local path. Use this when preserving the same app identity while installing a new build on the selected device.',
   positionalArgs: ['app', 'path'],
 } as const satisfies CommandSchemaOverride;
 

src/commands/react-native/index.ts

@@ -28,6 +28,8 @@ export const reactNativeCommandDefinition = defineExecutableCommand(
 const reactNativeCliSchema = {
   usageOverride: 'react-native dismiss-overlay',
   listUsageOverride: 'react-native dismiss-overlay',
+  helpDescription:
+    'Run supported React Native automation helpers. Use dismiss-overlay to close a visible development error overlay before continuing normal UI automation.',
   positionalArgs: ['dismiss-overlay'],
 } as const satisfies CommandSchemaOverride;
 

src/commands/system/index.ts

@@ -169,9 +169,21 @@ const appStateCliSchema = {
 
 const backCliSchema = {
   usageOverride: 'back [--in-app|--system]',
+  helpDescription:
+    'Navigate back in the app or through system navigation. Use in-app for the app navigation stack and system when the platform back behavior is required.',
   allowedFlags: ['backMode'],
 } as const satisfies CommandSchemaOverride;
 
+const homeCliSchema = {
+  helpDescription:
+    'Send the selected device to its home screen. This leaves the app session open but moves the foreground away from the app.',
+} as const satisfies CommandSchemaOverride;
+
+const appSwitcherCliSchema = {
+  helpDescription:
+    'Open the device app switcher to inspect or change foreground apps. This changes the visible system UI and may move focus away from the current app.',
+} as const satisfies CommandSchemaOverride;
+
 const orientationCliSchema = {
   usageOverride: 'orientation <portrait|portrait-upside-down|landscape-left|landscape-right>',
   helpDescription: 'Set device orientation on iOS and Android',
@@ -283,6 +295,7 @@ const homeCommandFacet = defineCommandFacet({
   name: HOME_COMMAND_NAME,
   metadata: homeCommandMetadata,
   definition: homeCommandDefinition,
+  cliSchema: homeCliSchema,
   cliReader: homeCliReader,
   daemonWriter: homeDaemonWriter,
   cliOutputFormatter: systemCliOutputFormatters.home,
@@ -302,6 +315,7 @@ const appSwitcherCommandFacet = defineCommandFacet({
   name: APP_SWITCHER_COMMAND_NAME,
   metadata: appSwitcherCommandMetadata,
   definition: appSwitcherCommandDefinition,
+  cliSchema: appSwitcherCliSchema,
   cliReader: appSwitcherCliReader,
   daemonWriter: appSwitcherDaemonWriter,
   cliOutputFormatter: systemCliOutputFormatters['app-switcher'],