fix: clarify element and device selection guidance

Author: KazuCocoa

src/tests/tools/llm-wording.test.ts

@@ -22,6 +22,30 @@ jest.unstable_mockModule('../../command', () => ({
   findElement: jest.fn(),
 }));
 
+jest.unstable_mockModule('../../devicemanager/adb-manager', () => ({
+  ADBManager: jest.fn(),
+}));
+
+jest.unstable_mockModule('../../devicemanager/ios-manager', () => ({
+  IOSManager: jest.fn(),
+}));
+
+jest.unstable_mockModule('../../logger', () => ({
+  default: {
+    debug: jest.fn(),
+    error: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+  },
+}));
+
+jest.unstable_mockModule('../../ui/mcp-ui-utils', () => ({
+  addUIResourceToResponse: jest.fn(),
+  createAppListUI: jest.fn(),
+  createDevicePickerUI: jest.fn(),
+  createUIResource: jest.fn(),
+}));
+
 jest.unstable_mockModule('../../tools/session/attach-session', () => ({
   attachSessionAction: jest.fn(),
 }));
@@ -97,7 +121,9 @@ describe('LLM-facing MCP tool wording', () => {
       /Android.*prefer.*android uiautomator/i
     );
     expect(strategyDescription).toMatch(/xpath last/i);
-    expect(selectorDescription).toMatch(/not natural language/i);
+    expect(selectorDescription).toMatch(
+      /do not pass natural-language descriptions/i
+    );
   });
 
   test('appium_session_management explains local vs remote session creation', async () => {
@@ -141,6 +167,35 @@ describe('LLM-facing MCP tool wording', () => {
     expect(tool.annotations?.destructiveHint).toBe(true);
   });
 
+  test('select_device preserves the local and remote workflow', async () => {
+    const tool = await registerTool('../../tools/session/select-device.js');
+    const description = normalizeText(tool.description);
+
+    expect(tool.name).toBe('select_device');
+    expect(description).toMatch(/LOCAL servers ONLY/i);
+    expect(description).toMatch(/ASK THE USER.*Android.*iOS.*do not assume/i);
+    expect(description).toMatch(/without deviceUdid.*list/i);
+    expect(description).toMatch(/one result.*auto-select/i);
+    expect(description).toMatch(
+      /multiple results.*ask the user.*chosen deviceUdid/i
+    );
+    expect(description).toMatch(/NEVER use.*REMOTE.*remoteServerUrl/i);
+    expect(description).toMatch(
+      /prepare_ios_simulator.*appium_session_management.*create/i
+    );
+    expect(description).toMatch(/Remote devices.*session capabilities/i);
+
+    expect(normalizeText(paramDescription(tool, 'platform'))).toMatch(
+      /user-selected.*never assume/i
+    );
+    expect(normalizeText(paramDescription(tool, 'iosDeviceType'))).toMatch(
+      /Required.*iOS.*simulator.*real/i
+    );
+    expect(normalizeText(paramDescription(tool, 'deviceUdid'))).toMatch(
+      /omit.*list.*ask.*multiple/i
+    );
+  });
+
   test('appium_mobile_permissions retains action-specific requirements', async () => {
     const tool = await registerTool(
       '../../tools/app-management/permissions.js'

src/tools/interactions/find.ts

@@ -24,14 +24,14 @@ export const findElementSchema = z.object({
       'css selector',
     ])
     .describe(
-      'Prefer accessibility id (cross-platform, fastest, stable), then id. ' +
-        'iOS: prefer -ios predicate/class chain; Android: prefer -android uiautomator. ' +
-        'Use xpath last. CSS is webview-only; appium_ai handles natural language/vision.'
+      'Priority: (1) accessibility id (cross-platform, fastest, stable), (2) id, ' +
+        '(3) iOS: prefer -ios predicate/class chain; Android: prefer -android uiautomator, (4) xpath LAST RESORT (slow/brittle). ' +
+        'name/class are fallbacks; CSS is webview-only. Use appium_ai action=find_element for natural language/vision.'
     ),
   selector: z
     .string()
     .describe(
-      'Selector for strategy; not natural language (use appium_ai for that).'
+      'Selector string for the chosen strategy. Do not pass natural-language descriptions; use appium_ai action=find_element.'
     ),
   sessionId: z
     .string()
@@ -44,7 +44,8 @@ export default function findElement(server: FastMCP): void {
     name: 'appium_find_element',
     description:
       'Find one element by strategy and selector; return its interaction UUID. ' +
-      'Prefer accessibility id over id before xpath, which is a last resort. Use appium_gesture scroll_to_element off-screen and appium_ai find_element for vision/natural language.',
+      'Prefer accessibility id over id before xpath, which is a last resort. ' +
+      'This tool does not scroll: use appium_gesture scroll_to_element for off-screen targets. Use appium_ai find_element for vision/natural-language targets.',
     parameters: findElementSchema,
     annotations: {
       readOnlyHint: true,

src/tools/session/select-device.ts

@@ -81,22 +81,23 @@ export default function selectDevice(server: any): void {
   server.addTool({
     name: 'select_device',
     description:
-      'LOCAL servers only: ask the user for platform, list devices, then select deviceUdid; one result auto-selects. ' +
-      'For iOS also pass iosDeviceType and prepare simulators before session create. ' +
-      'Skip for REMOTE servers; pass device capabilities to appium_session_management.',
+      'LOCAL servers ONLY; NEVER use for REMOTE/remoteServerUrl. ASK THE USER Android or iOS—do not assume. ' +
+      'Call without deviceUdid to list: one result auto-selects; for multiple results ask the user, then call again with the chosen deviceUdid. ' +
+      'For iOS require iosDeviceType and run prepare_ios_simulator before appium_session_management create. ' +
+      'Remote devices are selected through session capabilities.',
     parameters: z
       .object({
         platform: z
           .enum(['ios', 'android'])
-          .describe('Platform selected by the user.'),
+          .describe('User-selected platform; never assume.'),
         iosDeviceType: z
           .enum(['simulator', 'real'])
           .optional()
           .describe('Required for iOS: simulator or real.'),
         deviceUdid: z
           .string()
           .optional()
-          .describe('Chosen UDID; omit to list devices.'),
+          .describe('Chosen UDID; omit to list, then ask if multiple.'),
       })
       .refine(
         (data) => data.platform !== 'ios' || data.iosDeviceType !== undefined,