docs: Update tooling description to reflect usability

Author: Winify

src/tools/click.tool.ts

@@ -9,7 +9,7 @@ const defaultTimeout: number = 3000;
 
 export const clickToolDefinition: ToolDefinition = {
   name: 'click_element',
-  description: 'clicks an element',
+  description: 'Waits for an element to exist, scrolls it into view, and calls element.click(). For browser sessions. On iOS, element.click() is sometimes ignored — use tap_element (which calls element.tap()) instead.',
   inputSchema: {
     selector: z.string().describe('Value for the selector, in the form of css selector or xpath ("button.my-class" or "//button[@class=\'my-class\']" or "button=Exact text with spaces" or "a*=Link containing text")'),
     scrollToView: coerceBoolean.optional().describe('Whether to scroll the element into view before clicking').default(true),

src/tools/context.tool.ts

@@ -6,7 +6,7 @@ import { getBrowser } from '../session/state';
 
 export const switchContextToolDefinition: ToolDefinition = {
   name: 'switch_context',
-  description: 'switches between native and webview contexts',
+  description: 'Switches between native and webview automation contexts in a hybrid mobile app. Required before using CSS/XPath selectors inside an embedded webview — switch to WEBVIEW_* first, then switch back to NATIVE_APP for native elements. List available contexts from wdio://session/current/contexts.',
   inputSchema: {
     context: z
       .string()

src/tools/cookies.tool.ts

@@ -7,7 +7,7 @@ import { coerceBoolean } from '../utils/zod-helpers';
 
 export const setCookieToolDefinition: ToolDefinition = {
   name: 'set_cookie',
-  description: 'sets a cookie with specified name, value, and optional attributes',
+  description: 'Sets a browser cookie for the active session. The browser must already be on the target domain — cookies cannot be set cross-domain. Use to inject session tokens or feature flags without going through login flows.',
   inputSchema: {
     name: z.string().describe('Cookie name'),
     value: z.string().describe('Cookie value'),

src/tools/device.tool.ts

@@ -6,21 +6,21 @@ import { getBrowser } from '../session/state';
 
 export const hideKeyboardToolDefinition: ToolDefinition = {
   name: 'hide_keyboard',
-  description: 'hides the on-screen keyboard',
+  description: 'Dismisses the software keyboard on mobile. Call after text entry when the keyboard obscures elements you need to interact with next. No-op if already hidden. Mobile-only.',
   inputSchema: {},
 };
 
 export const rotateDeviceToolDefinition: ToolDefinition = {
   name: 'rotate_device',
-  description: 'rotates device to portrait or landscape orientation',
+  description: 'Rotates a mobile device to portrait or landscape and waits for the OS rotation to complete. Use to test orientation-dependent layouts. Mobile-only; no effect in browser sessions.',
   inputSchema: {
     orientation: z.enum(['PORTRAIT', 'LANDSCAPE']).describe('Device orientation'),
   },
 };
 
 export const setGeolocationToolDefinition: ToolDefinition = {
   name: 'set_geolocation',
-  description: 'sets device geolocation (latitude, longitude, altitude)',
+  description: 'Overrides the device GPS coordinates for the session. Affects navigator.geolocation on web and location services on mobile. Location permissions must be granted to the app before calling this.',
   inputSchema: {
     latitude: z.number().min(-90).max(90).describe('Latitude coordinate'),
     longitude: z.number().min(-180).max(180).describe('Longitude coordinate'),

src/tools/gestures.tool.ts

@@ -7,7 +7,7 @@ import { getBrowser } from '../session/state';
 // Tap Tool
 export const tapElementToolDefinition: ToolDefinition = {
   name: 'tap_element',
-  description: 'taps an element by selector or screen coordinates (mobile)',
+  description: 'Calls element.tap() on a matched element or taps at absolute screen coordinates. Use on iOS when element.click() (click_element) is ignored — tap is the native gesture iOS responds to. Mobile-only.',
   inputSchema: {
     selector: z
       .string()
@@ -61,7 +61,7 @@ export const tapElementTool: ToolCallback = async (args: {
 // Swipe Tool
 export const swipeToolDefinition: ToolDefinition = {
   name: 'swipe',
-  description: 'performs a swipe gesture in specified direction (mobile)',
+  description: 'Performs a full-screen swipe gesture on mobile. Direction is content movement (e.g. "up" scrolls a list upward, not the finger direction). Use to scroll past visible bounds; for moving a specific element use drag_and_drop. Mobile-only — use scroll for browsers.',
   inputSchema: {
     direction: z.enum(['up', 'down', 'left', 'right']).describe('Swipe direction'),
     duration: z

src/tools/navigate.tool.ts

@@ -6,7 +6,7 @@ import type { ToolDefinition } from '../types/tool';
 
 export const navigateToolDefinition: ToolDefinition = {
   name: 'navigate',
-  description: 'navigates to a URL',
+  description: 'Loads a URL in the current tab and waits for the page load event. Resets page state (DOM, JS runtime). Use instead of clicking links to go directly to a known URL.',
   inputSchema: {
     url: z.string().min(1).describe('The URL to navigate to'),
   },

src/tools/session.tool.ts

@@ -15,7 +15,7 @@ const automationEnum = z.enum(['XCUITest', 'UiAutomator2']);
 
 export const startSessionToolDefinition: ToolDefinition = {
   name: 'start_session',
-  description: 'Starts a browser or mobile app session. For local browser, use browser platform. For mobile apps, use ios or android platform. Use attach mode to connect to an existing Chrome instance.',
+  description: 'Starts a new browser or mobile automation session. Only one active session at a time — starting a new one closes the existing one. Use platform "browser" with a browser name, or "ios"/"android" with a deviceName. Use attach mode to connect to an already-running Chrome instance via CDP.',
   inputSchema: {
     provider: z.enum(['local', 'browserstack']).optional().default('local').describe('Session provider (default: local)'),
     platform: platformEnum.describe('Session platform type'),
@@ -94,7 +94,7 @@ type StartSessionArgs = {
 
 export const closeSessionToolDefinition: ToolDefinition = {
   name: 'close_session',
-  description: 'Closes or detaches from the current browser or app session',
+  description: 'Closes or detaches from the current session. Detach disconnects without terminating the process, preserving app state on the Appium server. Sessions started with noReset: true auto-detach by default.',
   inputSchema: {
     detach: coerceBoolean.optional().describe('If true, disconnect without terminating (preserves app state). Default: false'),
   },

src/tools/set-value.tool.ts

@@ -9,7 +9,7 @@ const defaultTimeout: number = 3000;
 
 export const setValueToolDefinition: ToolDefinition = {
   name: 'set_value',
-  description: 'set value to an element, aka typing',
+  description: 'Clears an input or textarea and types the given text. Always replaces existing content. Fails if the element is not found or not interactable within the timeout.',
   inputSchema: {
     selector: z.string().describe('Value for the selector, in the form of css selector or xpath ("button.my-class" or "//button[@class=\'my-class\']")'),
     value: z.string().describe('Text to enter into the element'),

src/tools/tabs.tool.ts

@@ -6,7 +6,7 @@ import { getBrowser } from '../session/state';
 
 export const switchTabToolDefinition: ToolDefinition = {
   name: 'switch_tab',
-  description: 'switches to a browser tab by handle or index',
+  description: 'Focuses a browser tab by window handle or 0-based index. All subsequent tool calls operate on the newly active tab. Get handles from wdio://session/current/tabs. Browser-only — use switch_context for mobile webviews.',
   inputSchema: {
     handle: z.string().optional().describe('Window handle to switch to'),
     index: z.number().int().min(0).optional().describe('0-based tab index to switch to'),