junis 0.3.1 → 0.3.3

package/dist/server/stdio.js

@@ -101,11 +101,26 @@ var FilesystemTools = class {
   register(server) {
     server.tool(
       "execute_command",
-      "Execute terminal command",
+      [
+        "Execute a shell command on the user's local device.",
+        "",
+        "ROUTING:",
+        "- Use for system commands, package managers (npm, pip, brew), git, build tools, and scripting.",
+        "- For reading files prefer read_file, for editing prefer edit_block, for searching prefer search_code.",
+        "",
+        "BEHAVIOR:",
+        "- Safe, routine commands (ls, pwd, git status, echo): execute immediately without explanation.",
+        "- Destructive or irreversible commands (rm -rf, sudo, shutdown, mkfs): explain what will happen and get user confirmation first.",
+        "- If a command fails, analyze the error and suggest an alternative. Do not retry the identical command more than twice.",
+        "",
+        "SAFETY:",
+        "- Commands run with the user's full permissions. Never execute commands that could damage the system, expose credentials, or modify security settings without explicit user request.",
+        "- Avoid piping untrusted input into shells. Use absolute paths when possible. Quote paths containing spaces."
+      ].join("\n"),
       {
-        command: import_zod.z.string().describe("Shell command to execute"),
-        timeout_ms: import_zod.z.number().optional().default(3e4).describe("Timeout (ms)"),
-        background: import_zod.z.boolean().optional().default(false).describe("Run in background")
+        command: import_zod.z.string().describe("The shell command to execute. Use absolute paths when possible. Quote paths containing spaces."),
+        timeout_ms: import_zod.z.number().optional().default(3e4).describe("Maximum execution time in milliseconds (default: 30000). Increase for long-running builds or downloads."),
+        background: import_zod.z.boolean().optional().default(false).describe("Run in background without waiting for completion. Use for servers or long-running processes.")
       },
       async ({ command, timeout_ms, background }) => {
         checkPermission("execute_command");
@@ -137,10 +152,15 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "read_file",
-      "Read file",
+      [
+        "Read the contents of a file from the local filesystem.",
+        "",
+        "Returns file content as text (utf-8) or base64 for binary files. Supports any file type.",
+        "For searching within files, prefer search_code instead. For listing directory contents, use list_directory."
+      ].join("\n"),
       {
-        path: import_zod.z.string().describe("File path"),
-        encoding: import_zod.z.enum(["utf-8", "base64"]).optional().default("utf-8").describe("Encoding")
+        path: import_zod.z.string().describe("Absolute or relative file path to read"),
+        encoding: import_zod.z.enum(["utf-8", "base64"]).optional().default("utf-8").describe("'utf-8' for text files (default), 'base64' for binary files (images, PDFs, archives)")
       },
       async ({ path: filePath, encoding }) => {
         try {
@@ -157,10 +177,15 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "write_file",
-      "Write/create file",
+      [
+        "Create a new file or completely overwrite an existing file. Parent directories are created automatically.",
+        "",
+        "WARNING: This replaces the entire file content. For partial modifications, use edit_block instead.",
+        "Prefer edit_block over write_file for existing files \u2014 it's safer and preserves unmodified content."
+      ].join("\n"),
       {
-        path: import_zod.z.string().describe("File path"),
-        content: import_zod.z.string().describe("File content")
+        path: import_zod.z.string().describe("File path to create or overwrite. Parent directories are auto-created."),
+        content: import_zod.z.string().describe("Complete file content. This replaces the entire file.")
       },
       async ({ path: filePath, content }) => {
         checkPermission("write_file");
@@ -171,9 +196,12 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "list_directory",
-      "List directory contents",
+      [
+        "List files and subdirectories in the specified path. Returns entries with type indicators (\u{1F4C1} directory, \u{1F4C4} file).",
+        "Use this to explore project structure before reading or modifying files."
+      ].join("\n"),
       {
-        path: import_zod.z.string().describe("Directory path")
+        path: import_zod.z.string().describe("Directory path to list")
       },
       async ({ path: dirPath }) => {
         try {
@@ -191,11 +219,16 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "search_code",
-      "Search code/text",
+      [
+        "Search for text patterns across files using regex. Uses ripgrep for speed with glob fallback.",
+        "",
+        "Use this to find code definitions, function references, configuration values, or any text pattern.",
+        "Returns matching lines with file paths and line numbers for precise navigation."
+      ].join("\n"),
       {
-        pattern: import_zod.z.string().describe("Search pattern (regex supported)"),
-        directory: import_zod.z.string().optional().default(".").describe("Search directory"),
-        file_pattern: import_zod.z.string().optional().default("**/*").describe("File pattern")
+        pattern: import_zod.z.string().describe("Search pattern with full regex support (e.g. 'function\\s+\\w+', 'import.*from', 'TODO')"),
+        directory: import_zod.z.string().optional().default(".").describe("Root directory to search from (default: current working directory)"),
+        file_pattern: import_zod.z.string().optional().default("**/*").describe("Glob pattern to filter files (e.g. '**/*.ts', '*.py', 'src/**/*.js')")
       },
       async ({ pattern, directory, file_pattern }) => {
         try {
@@ -233,7 +266,7 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "list_processes",
-      "List running processes",
+      "List the top 30 running processes sorted by CPU usage. Use this to identify resource-heavy processes, find PIDs for kill_process, or diagnose performance issues.",
       {},
       async () => {
         const cmd = process.platform === "win32" ? "tasklist" : process.platform === "darwin" ? "ps aux | sort -rk 3 | head -30" : "ps aux --sort=-%cpu | head -30";
@@ -243,10 +276,14 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "kill_process",
-      "Kill process (SIGTERM then 3s wait, auto SIGKILL if still alive)",
+      [
+        "Terminate a process by PID. Default: sends SIGTERM (graceful shutdown), waits 3 seconds, then auto-applies SIGKILL if still alive.",
+        "",
+        "SAFETY: Only kill processes the user explicitly identifies. Never kill system-critical processes (init, systemd, loginwindow, WindowServer) without explicit instruction."
+      ].join("\n"),
       {
-        pid: import_zod.z.number().describe("PID of the process to kill"),
-        signal: import_zod.z.enum(["SIGTERM", "SIGKILL"]).optional().default("SIGTERM").describe("Initial signal (default: SIGTERM). SIGKILL for immediate force kill)")
+        pid: import_zod.z.number().describe("PID of the process to terminate (use list_processes to find PIDs)"),
+        signal: import_zod.z.enum(["SIGTERM", "SIGKILL"]).optional().default("SIGTERM").describe("SIGTERM (default): graceful shutdown with 3s auto-SIGKILL fallback. SIGKILL: immediate force kill.")
       },
       async ({ pid, signal }) => {
         const isWindows = process.platform === "win32";
@@ -292,12 +329,20 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "edit_block",
-      "Replace a specific text block in a file with new text (diff-based partial edit)",
+      [
+        "Replace a specific text block in a file with new text (diff-based partial edit).",
+        "",
+        "WORKFLOW: Always use read_file first to see current content, then use edit_block with the exact text to replace.",
+        "The old_string must match character-for-character including whitespace, indentation, and line breaks.",
+        "If multiple matches exist, include more surrounding context to make it unique, or set replace_all=true.",
+        "",
+        "Prefer this over write_file for modifying existing files \u2014 it only changes what you specify and preserves the rest."
+      ].join("\n"),
       {
-        path: import_zod.z.string().describe("File path"),
-        old_string: import_zod.z.string().describe("Existing text to replace (must match exactly)"),
-        new_string: import_zod.z.string().describe("New text"),
-        replace_all: import_zod.z.boolean().optional().default(false).describe("If true, replace all matches; if false, replace only the first")
+        path: import_zod.z.string().describe("Path to the file to edit. The file must already exist."),
+        old_string: import_zod.z.string().describe("The exact text to find and replace. Must match character-for-character including whitespace and newlines. Include enough context for uniqueness."),
+        new_string: import_zod.z.string().describe("The replacement text. Use empty string to delete the matched text."),
+        replace_all: import_zod.z.boolean().optional().default(false).describe("If true, replace ALL matches. If false (default), require exactly one match (errors on ambiguous multiple matches).")
       },
       async ({ path: filePath, old_string, new_string, replace_all }) => {
         const content = await import_promises.default.readFile(filePath, "utf-8");
@@ -332,11 +377,16 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "cron_create",
-      "Create a recurring cron job. schedule uses cron syntax (e.g. '0 9 * * 1-5' = weekdays 9am).",
+      [
+        "Create a recurring scheduled task (cron job) using standard cron syntax.",
+        "",
+        "Common schedules: '*/5 * * * *' (every 5 min), '0 9 * * 1-5' (weekdays 9am), '0 0 * * *' (daily midnight), '0 */2 * * *' (every 2 hours).",
+        "Duplicate commands are automatically detected and rejected. Use cron_list to see existing jobs."
+      ].join("\n"),
       {
-        schedule: import_zod.z.string().describe("Cron schedule expression (e.g. '*/5 * * * *' for every 5 min, '0 9 * * 1-5' for weekdays 9am)"),
-        command: import_zod.z.string().describe("Shell command to execute"),
-        label: import_zod.z.string().optional().describe("Optional label/comment for identification")
+        schedule: import_zod.z.string().describe("Cron schedule expression (5 fields: minute hour day month weekday). Examples: '*/5 * * * *' (every 5 min), '0 9 * * 1-5' (weekdays 9am)"),
+        command: import_zod.z.string().describe("Shell command to execute on schedule"),
+        label: import_zod.z.string().optional().describe("Human-readable label for identification (e.g. 'daily-backup', 'log-cleanup')")
       },
       async ({ schedule, command, label }) => {
         try {
@@ -378,7 +428,7 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "cron_list",
-      "List all cron jobs in the current user's crontab",
+      "List all scheduled cron jobs with their IDs, labels, schedules, and commands. Use the returned ID numbers with cron_delete to remove specific jobs.",
       {},
       async () => {
         try {
@@ -425,10 +475,10 @@ ${error.stderr ?? ""}`
     );
     server.tool(
       "cron_delete",
-      "Delete a cron job by its ID (from cron_list) or by matching command string",
+      "Delete a scheduled cron job by its ID (from cron_list output) or by matching command string. Associated comment labels are automatically cleaned up.",
       {
-        id: import_zod.z.number().optional().describe("Cron job ID from cron_list output"),
-        command: import_zod.z.string().optional().describe("Delete job matching this command string")
+        id: import_zod.z.number().optional().describe("Cron job ID from cron_list output (e.g. 1, 2, 3)"),
+        command: import_zod.z.string().optional().describe("Delete all jobs matching this command string")
       },
       async ({ id, command }) => {
         if (!id && !command) {
@@ -541,13 +591,22 @@ var BrowserTools = class {
     };
     server.tool(
       "browser_start",
-      "Start browser (BrowserClaw). mode='managed'(default) launches new Chromium; mode='remote-cdp' connects to existing Chrome via CDP URL.",
+      [
+        "Launch or connect to a web browser for automation.",
+        "",
+        "MODES:",
+        "- 'managed' (default): Launches a new Chromium instance. Use 'headless' for background operation, 'profile' for persistent sessions (cookies, logins preserved).",
+        "- 'remote-cdp': Connects to an already-running Chrome via CDP URL (e.g. from chrome://inspect). Use this to automate an existing browser session.",
+        "",
+        "WORKFLOW: browser_start \u2192 browser_navigate \u2192 browser_snapshot \u2192 interact (click/type/fill) \u2192 browser_stop.",
+        "Always call browser_stop when done to release system resources."
+      ].join("\n"),
       {
-        mode: import_zod2.z.enum(["managed", "remote-cdp"]).optional().default("managed").describe("'managed' = launch new browser, 'remote-cdp' = connect to existing Chrome"),
-        headless: import_zod2.z.boolean().optional().default(false).describe("Run headless (managed mode only)"),
-        cdpUrl: import_zod2.z.string().optional().describe("CDP URL for remote-cdp mode (e.g. http://localhost:9222)"),
-        profile: import_zod2.z.string().optional().describe("Profile name (managed mode only)"),
-        allowInternal: import_zod2.z.boolean().optional().default(false).describe("Allow localhost/internal URLs")
+        mode: import_zod2.z.enum(["managed", "remote-cdp"]).optional().default("managed").describe("'managed' = launch new browser, 'remote-cdp' = connect to existing Chrome via CDP"),
+        headless: import_zod2.z.boolean().optional().default(false).describe("Run without visible window (managed mode only). Use for background tasks."),
+        cdpUrl: import_zod2.z.string().optional().describe("Chrome DevTools Protocol URL for remote-cdp mode (e.g. http://localhost:9222)"),
+        profile: import_zod2.z.string().optional().describe("Browser profile name for persistent sessions \u2014 preserves cookies, logins, and history across restarts (managed mode only)"),
+        allowInternal: import_zod2.z.boolean().optional().default(false).describe("Allow navigation to localhost and internal network URLs")
       },
       ({ mode, headless, cdpUrl, profile, allowInternal }) => this.withLock(async () => {
         if (this.browser) {
@@ -568,7 +627,7 @@ var BrowserTools = class {
     );
     server.tool(
       "browser_stop",
-      "Stop browser and release resources",
+      "Stop the browser and release all associated resources (memory, connections, processes). Always call this when browser automation is complete.",
       {},
       () => this.withLock(async () => {
         await this.cleanup();
@@ -577,9 +636,9 @@ var BrowserTools = class {
     );
     server.tool(
       "browser_navigate",
-      "Navigate to URL. Opens new tab if browser started but no page yet.",
+      "Navigate the browser to a URL. Automatically opens a new tab if the browser is started but no page exists yet. Waits for the page to load before returning.",
       {
-        url: import_zod2.z.string().describe("URL to navigate to")
+        url: import_zod2.z.string().describe("Full URL to navigate to (include https://)")
       },
       ({ url }) => this.withLock(async () => {
         if (!this.browser) throw new Error("Browser not started. Call browser_start first.");
@@ -594,10 +653,17 @@ var BrowserTools = class {
     );
     server.tool(
       "browser_snapshot",
-      "Get Accessibility Tree snapshot with ref numbers. Use refs to interact with elements (e.g. browser_click with ref='e1').",
+      [
+        "Capture the page's Accessibility Tree with numbered ref IDs for each element. This is the primary way to 'see' and understand page content.",
+        "",
+        "WORKFLOW: Call browser_snapshot \u2192 find the target element's ref (e.g. 'e1', 'e5') \u2192 use that ref in browser_click, browser_type, or other interaction tools.",
+        "Refs change after page updates \u2014 always call browser_snapshot again after navigation or clicks that modify the page.",
+        "",
+        "Prefer this over browser_screenshot for understanding page structure \u2014 it's faster, structured, and machine-readable."
+      ].join("\n"),
       {
-        interactive: import_zod2.z.boolean().optional().default(true).describe("Only include interactive elements"),
-        compact: import_zod2.z.boolean().optional().default(true).describe("Remove empty containers")
+        interactive: import_zod2.z.boolean().optional().default(true).describe("true (default): only show clickable/typeable elements. false: show all elements including static text."),
+        compact: import_zod2.z.boolean().optional().default(true).describe("true (default): hide empty containers for cleaner output")
       },
       ({ interactive, compact }) => this.withLock(async () => {
         const result = await requirePage().snapshot({ interactive, compact });
@@ -617,11 +683,11 @@ ${refList}`
     );
     server.tool(
       "browser_click",
-      "Click element by ref number from browser_snapshot",
+      "Click an element by its ref number from browser_snapshot. Always call browser_snapshot first to get current refs \u2014 they change after page updates.",
       {
-        ref: import_zod2.z.string().describe("Ref number from snapshot (e.g. 'e1')"),
-        doubleClick: import_zod2.z.boolean().optional().default(false),
-        button: import_zod2.z.enum(["left", "right", "middle"]).optional().default("left")
+        ref: import_zod2.z.string().describe("Element ref from browser_snapshot (e.g. 'e1', 'e15'). Call browser_snapshot first to get current refs."),
+        doubleClick: import_zod2.z.boolean().optional().default(false).describe("Double-click instead of single click"),
+        button: import_zod2.z.enum(["left", "right", "middle"]).optional().default("left").describe("Mouse button to use")
       },
       ({ ref, doubleClick, button }) => this.withLock(async () => {
         await requirePage().click(ref, { doubleClick, button });
@@ -630,12 +696,12 @@ ${refList}`
     );
     server.tool(
       "browser_type",
-      "Type text into element by ref number",
+      "Type text into an input element by ref number. Use 'submit=true' to press Enter after typing (e.g. for search forms). Use 'slowly=true' for sites requiring keystroke-by-keystroke input.",
       {
-        ref: import_zod2.z.string().describe("Ref number from snapshot"),
-        text: import_zod2.z.string().describe("Text to type"),
-        submit: import_zod2.z.boolean().optional().default(false).describe("Press Enter after typing"),
-        slowly: import_zod2.z.boolean().optional().default(false).describe("Type slowly (75ms per char)")
+        ref: import_zod2.z.string().describe("Element ref from browser_snapshot (e.g. 'e3')"),
+        text: import_zod2.z.string().describe("Text to type into the element"),
+        submit: import_zod2.z.boolean().optional().default(false).describe("Press Enter after typing (useful for search boxes and forms)"),
+        slowly: import_zod2.z.boolean().optional().default(false).describe("Type slowly (75ms per char) for sites that process each keystroke")
       },
       ({ ref, text, submit, slowly }) => this.withLock(async () => {
         await requirePage().type(ref, text, { submit, slowly });
@@ -644,13 +710,13 @@ ${refList}`
     );
     server.tool(
       "browser_fill",
-      "Fill multiple form fields at once",
+      "Fill multiple form fields at once \u2014 more efficient than calling browser_type repeatedly. Each field needs a ref from browser_snapshot.",
       {
         fields: import_zod2.z.array(import_zod2.z.object({
           ref: import_zod2.z.string(),
           type: import_zod2.z.enum(["text", "checkbox", "radio"]),
           value: import_zod2.z.union([import_zod2.z.string(), import_zod2.z.boolean()])
-        })).describe("Array of {ref, type, value}")
+        })).describe("Array of {ref, type, value}. type='text': value is string. type='checkbox'/'radio': value is boolean.")
       },
       ({ fields }) => this.withLock(async () => {
         await requirePage().fill(fields);
@@ -659,9 +725,9 @@ ${refList}`
     );
     server.tool(
       "browser_select",
-      "Select dropdown option(s) by ref",
+      "Select one or more options from a dropdown/select element. Values should match the option value attributes, not display text.",
       {
-        ref: import_zod2.z.string().describe("Ref number from snapshot"),
+        ref: import_zod2.z.string().describe("Ref of the <select> element from browser_snapshot"),
         values: import_zod2.z.array(import_zod2.z.string()).describe("Option value(s) to select")
       },
       ({ ref, values }) => this.withLock(async () => {
@@ -671,9 +737,9 @@ ${refList}`
     );
     server.tool(
       "browser_press",
-      "Press keyboard key or combination (e.g. 'Enter', 'Control+a', 'Escape')",
+      "Press a keyboard key or key combination. Use for shortcuts (e.g. 'Control+a', 'Escape'), form submission ('Enter'), or navigation ('Tab'). Does not require a specific element ref.",
       {
-        key: import_zod2.z.string().describe("Key combination (e.g. 'Enter', 'Control+a', 'Escape', 'Tab')")
+        key: import_zod2.z.string().describe("Key or combination: 'Enter', 'Escape', 'Tab', 'Control+a', 'Meta+c', 'ArrowDown', 'Backspace'")
       },
       ({ key }) => this.withLock(async () => {
         await requirePage().press(key);
@@ -682,9 +748,9 @@ ${refList}`
     );
     server.tool(
       "browser_hover",
-      "Hover mouse over element by ref",
+      "Move the mouse cursor over an element by ref. Use to trigger hover menus, tooltips, or dropdown previews before clicking.",
       {
-        ref: import_zod2.z.string().describe("Ref number from snapshot")
+        ref: import_zod2.z.string().describe("Element ref from browser_snapshot")
       },
       ({ ref }) => this.withLock(async () => {
         await requirePage().hover(ref);
@@ -693,10 +759,10 @@ ${refList}`
     );
     server.tool(
       "browser_drag",
-      "Drag element from startRef to endRef",
+      "Drag an element from startRef to endRef. Both refs must come from a recent browser_snapshot. Use for drag-and-drop interfaces, sliders, or reorderable lists.",
       {
-        startRef: import_zod2.z.string().describe("Source element ref"),
-        endRef: import_zod2.z.string().describe("Target element ref")
+        startRef: import_zod2.z.string().describe("Source element ref to drag from"),
+        endRef: import_zod2.z.string().describe("Target element ref to drag to")
       },
       ({ startRef, endRef }) => this.withLock(async () => {
         await requirePage().drag(startRef, endRef);
@@ -705,10 +771,10 @@ ${refList}`
     );
     server.tool(
       "browser_upload",
-      "Upload file(s) to file input element by ref",
+      "Upload local files to a file input element (<input type='file'>). The ref must point to a file input from browser_snapshot.",
       {
-        ref: import_zod2.z.string().describe("Ref number of file input element"),
-        paths: import_zod2.z.array(import_zod2.z.string()).describe("Absolute file path(s) to upload")
+        ref: import_zod2.z.string().describe("Ref of the file input element from browser_snapshot"),
+        paths: import_zod2.z.array(import_zod2.z.string()).describe("Absolute file path(s) on the local device to upload")
       },
       ({ ref, paths }) => this.withLock(async () => {
         await requirePage().uploadFile(ref, paths);
@@ -717,11 +783,16 @@ ${refList}`
     );
     server.tool(
       "browser_screenshot",
-      "Take screenshot of current page",
+      [
+        "Capture a screenshot of the current page. Returns base64 image data (viewable by AI) or saves to a file.",
+        "",
+        "Prefer browser_snapshot (Accessibility Tree) for understanding page structure \u2014 it's faster and machine-readable.",
+        "Use browser_screenshot only when visual layout matters (charts, images, styling, visual verification)."
+      ].join("\n"),
       {
-        path: import_zod2.z.string().optional().describe("Save path (if omitted, returns base64)"),
-        fullPage: import_zod2.z.boolean().optional().default(false),
-        ref: import_zod2.z.string().optional().describe("Capture specific element by ref")
+        path: import_zod2.z.string().optional().describe("Save path for the screenshot. If omitted, returns base64 image data directly."),
+        fullPage: import_zod2.z.boolean().optional().default(false).describe("Capture the full scrollable page, not just the visible viewport"),
+        ref: import_zod2.z.string().optional().describe("Capture only a specific element by its ref from browser_snapshot")
       },
       ({ path: path2, fullPage, ref }) => this.withLock(async () => {
         const buffer = await requirePage().screenshot({ fullPage, ref });
@@ -740,9 +811,9 @@ ${refList}`
     );
     server.tool(
       "browser_pdf",
-      "Save current page as PDF",
+      "Save the current page as a PDF file. Renders the full page including below-the-fold content. Useful for archiving, sharing, or offline reading.",
       {
-        path: import_zod2.z.string().describe("Save path (.pdf)")
+        path: import_zod2.z.string().describe("Output file path (.pdf)")
       },
       ({ path: path2 }) => this.withLock(async () => {
         const buffer = await requirePage().pdf();
@@ -752,9 +823,14 @@ ${refList}`
     );
     server.tool(
       "browser_evaluate",
-      "Execute JavaScript in page context",
+      [
+        "Execute JavaScript code directly in the browser page context and return the result.",
+        "",
+        "Use for: extracting data not available in the Accessibility Tree, DOM manipulation, interacting with page APIs, or debugging.",
+        "Wrap complex logic in an IIFE: (function(){ ... })()"
+      ].join("\n"),
       {
-        code: import_zod2.z.string().describe("JavaScript code to execute (wrap in function if needed)")
+        code: import_zod2.z.string().describe("JavaScript code to execute in the page context. Return values are automatically serialized.")
       },
       ({ code }) => this.withLock(async () => {
         try {
@@ -775,13 +851,17 @@ ${refList}`
     );
     server.tool(
       "browser_wait",
-      "Wait for a condition: text appearance/disappearance, URL pattern, or fixed time",
+      [
+        "Wait for a specific condition before proceeding. Use between actions when the page needs time to update.",
+        "",
+        "OPTIONS (use one): 'text' (wait for text to appear), 'textGone' (wait for text to disappear), 'url' (URL matches glob), 'loadState' (page load state), 'timeMs' (fixed delay as last resort)."
+      ].join("\n"),
       {
-        text: import_zod2.z.string().optional().describe("Wait until this text appears"),
-        textGone: import_zod2.z.string().optional().describe("Wait until this text disappears"),
-        url: import_zod2.z.string().optional().describe("Wait until URL matches (glob pattern, e.g. '**/dashboard')"),
-        loadState: import_zod2.z.enum(["load", "domcontentloaded", "networkidle"]).optional().describe("Wait for load state"),
-        timeMs: import_zod2.z.number().optional().describe("Wait fixed milliseconds")
+        text: import_zod2.z.string().optional().describe("Wait until this text appears on the page"),
+        textGone: import_zod2.z.string().optional().describe("Wait until this text disappears from the page"),
+        url: import_zod2.z.string().optional().describe("Wait until URL matches this glob pattern (e.g. '**/dashboard', '**/success')"),
+        loadState: import_zod2.z.enum(["load", "domcontentloaded", "networkidle"]).optional().describe("Wait for page load state: 'load' (full), 'domcontentloaded' (DOM ready), 'networkidle' (no pending requests)"),
+        timeMs: import_zod2.z.number().optional().describe("Fixed wait in milliseconds \u2014 use as last resort when other conditions don't apply")
       },
       ({ text, textGone, url, loadState, timeMs }) => this.withLock(async () => {
         const condition = {};
@@ -796,9 +876,9 @@ ${refList}`
     );
     server.tool(
       "browser_cookies",
-      "Get, set, or clear cookies",
+      "Manage browser cookies: get all cookies, set a specific cookie, or clear all cookies. Useful for authentication state, session management, or testing.",
       {
-        action: import_zod2.z.enum(["get", "set", "clear"]).describe("Action to perform"),
+        action: import_zod2.z.enum(["get", "set", "clear"]).describe("'get': retrieve all cookies, 'set': add/update a cookie, 'clear': remove all cookies"),
         cookie: import_zod2.z.object({
           name: import_zod2.z.string(),
           value: import_zod2.z.string(),
@@ -806,7 +886,7 @@ ${refList}`
           path: import_zod2.z.string().optional(),
           httpOnly: import_zod2.z.boolean().optional(),
           secure: import_zod2.z.boolean().optional()
-        }).optional().describe("Cookie data (required for set action)")
+        }).optional().describe("Cookie data (required for 'set' action)")
       },
       ({ action, cookie }) => this.withLock(async () => {
         const page = requirePage();
@@ -825,12 +905,12 @@ ${refList}`
     );
     server.tool(
       "browser_storage",
-      "Read/write/clear localStorage or sessionStorage",
+      "Read, write, or clear browser localStorage/sessionStorage. Useful for managing client-side state, authentication tokens, or application preferences.",
       {
-        action: import_zod2.z.enum(["get", "set", "clear"]).describe("Action to perform"),
-        kind: import_zod2.z.enum(["local", "session"]).optional().default("local").describe("Storage type"),
-        key: import_zod2.z.string().optional().describe("Storage key (get/set)"),
-        value: import_zod2.z.string().optional().describe("Value to set (set action)")
+        action: import_zod2.z.enum(["get", "set", "clear"]).describe("'get': read value(s), 'set': write a key-value pair, 'clear': remove all entries"),
+        kind: import_zod2.z.enum(["local", "session"]).optional().default("local").describe("'local' (persistent) or 'session' (cleared on tab close)"),
+        key: import_zod2.z.string().optional().describe("Storage key to get or set. Omit key with 'get' to retrieve all entries."),
+        value: import_zod2.z.string().optional().describe("Value to store (required for 'set' action)")
       },
       ({ action, kind, key, value }) => this.withLock(async () => {
         const page = requirePage();
@@ -850,13 +930,13 @@ ${refList}`
     server.tool(
       "browser_dialog",
       [
-        "Handle JavaScript dialogs (alert/confirm/prompt).",
-        "Two-step usage:",
-        "  1. action='arm'  \u2014 register a one-shot handler (returns immediately, does NOT block).",
+        "Handle JavaScript dialogs (alert, confirm, prompt). Two-step pattern:",
+        "  1. action='arm' \u2014 register a one-shot handler (returns immediately, does NOT block).",
         "  2. Trigger the dialog (e.g. browser_click on the button that calls confirm()).",
         "  3. action='wait' \u2014 await the handler to confirm the dialog was handled.",
+        "",
         "The 'accept' and 'promptText' params are only used with action='arm'."
-      ].join(" "),
+      ].join("\n"),
       {
         action: import_zod2.z.enum(["arm", "wait"]).describe(
           "'arm' = register handler and return immediately; 'wait' = await the previously armed handler"
@@ -868,7 +948,7 @@ ${refList}`
           "Text to enter if the dialog is a prompt. Only used with action='arm'."
         ),
         timeoutMs: import_zod2.z.number().optional().describe(
-          "Timeout in ms for 'wait' action. Default: 30000."
+          "Timeout in ms for 'wait' action (default: 30000). Increase for slow-loading dialogs."
         )
       },
       ({ action, accept, promptText, timeoutMs }) => this.withLock(async () => {
@@ -919,8 +999,8 @@ var NotebookTools = class {
   register(server) {
     server.tool(
       "notebook_read",
-      "Read .ipynb notebook",
-      { path: import_zod3.z.string().describe("Notebook file path") },
+      "Read a Jupyter notebook (.ipynb) and return all cells with their types (code/markdown), source content, and output counts. Use this to understand notebook structure before making edits.",
+      { path: import_zod3.z.string().describe("Path to the .ipynb notebook file") },
       async ({ path: filePath }) => {
         const nb = await readNotebook(filePath);
         const cells = nb.cells.map((cell, i) => ({
@@ -936,11 +1016,11 @@ var NotebookTools = class {
     );
     server.tool(
       "notebook_edit_cell",
-      "Edit a specific notebook cell",
+      "Replace the source code of a specific cell in a Jupyter notebook. Use notebook_read first to identify the correct cell index (0-based). Existing outputs for the cell are preserved \u2014 use notebook_execute to re-run.",
       {
-        path: import_zod3.z.string(),
-        cell_index: import_zod3.z.number().describe("Cell index (0-based)"),
-        source: import_zod3.z.string().describe("New source code")
+        path: import_zod3.z.string().describe("Path to the .ipynb notebook file"),
+        cell_index: import_zod3.z.number().describe("Cell index to edit (0-based). Use notebook_read to find the right index."),
+        source: import_zod3.z.string().describe("New source code/content for the cell (replaces entire cell content)")
       },
       async ({ path: filePath, cell_index, source }) => {
         const nb = await readNotebook(filePath);
@@ -956,10 +1036,15 @@ var NotebookTools = class {
     );
     server.tool(
       "notebook_execute",
-      "Execute notebook (nbconvert --execute)",
+      [
+        "Execute all cells in a Jupyter notebook using nbconvert. Results are saved in-place \u2014 the notebook file is updated with execution outputs.",
+        "",
+        "Requires Jupyter to be installed (pip install jupyter). The timeout applies per cell, not for the entire notebook.",
+        "If execution fails on a cell, the error is captured in the cell output and subsequent cells may not execute."
+      ].join("\n"),
       {
-        path: import_zod3.z.string().describe("Notebook file path"),
-        timeout: import_zod3.z.number().optional().default(300).describe("Timeout per cell (seconds)")
+        path: import_zod3.z.string().describe("Path to the .ipynb notebook file to execute"),
+        timeout: import_zod3.z.number().optional().default(300).describe("Maximum execution time per cell in seconds (default: 300). Increase for cells with heavy computation.")
       },
       async ({ path: filePath, timeout }) => {
         const nbconvertArgs = `nbconvert --to notebook --execute --inplace "${filePath}" --ExecutePreprocessor.timeout=${timeout}`;
@@ -988,12 +1073,12 @@ var NotebookTools = class {
     );
     server.tool(
       "notebook_add_cell",
-      "Add a new cell to notebook",
+      "Insert a new cell into a Jupyter notebook. If position is omitted, the cell is appended at the end. Use cell_type='code' for executable Python cells, 'markdown' for documentation/text cells.",
       {
-        path: import_zod3.z.string().describe(".ipynb file path"),
-        cell_type: import_zod3.z.enum(["code", "markdown"]).describe("Cell type"),
-        source: import_zod3.z.string().describe("Cell source content"),
-        position: import_zod3.z.number().optional().describe("Insert position (0-based). Appends to end if omitted")
+        path: import_zod3.z.string().describe("Path to the .ipynb notebook file"),
+        cell_type: import_zod3.z.enum(["code", "markdown"]).describe("'code' for executable cells, 'markdown' for text/documentation cells"),
+        source: import_zod3.z.string().describe("Cell source content (Python code or Markdown text)"),
+        position: import_zod3.z.number().optional().describe("Insert position (0-based index). Omit to append at the end. If position exceeds cell count, appends at end with a warning.")
       },
       async ({ path: filePath, cell_type: cellType, source, position }) => {
         const nb = await readNotebook(filePath);
@@ -1024,10 +1109,10 @@ var NotebookTools = class {
     );
     server.tool(
       "notebook_delete_cell",
-      "Delete a specific notebook cell",
+      "Delete a cell from a Jupyter notebook by its 0-based index. Use notebook_read first to verify the cell content before deletion. This action cannot be undone.",
       {
-        path: import_zod3.z.string().describe(".ipynb file path"),
-        cell_index: import_zod3.z.number().describe("Cell index to delete (0-based)")
+        path: import_zod3.z.string().describe("Path to the .ipynb notebook file"),
+        cell_index: import_zod3.z.number().describe("Cell index to delete (0-based). Use notebook_read first to verify content.")
       },
       async ({ path: filePath, cell_index }) => {
         const nb = await readNotebook(filePath);
@@ -1058,9 +1143,14 @@ var DeviceTools = class {
   register(server) {
     server.tool(
       "camera_capture",
-      "Camera photo capture",
+      [
+        "Capture a photo from the device's camera and return it as base64 image data.",
+        "",
+        "Platform-specific: macOS (imagesnap), Windows (ffmpeg/dshow), Linux (fswebcam).",
+        "Requires a connected camera with OS permissions granted. If output_path is provided, the file is also saved to disk."
+      ].join("\n"),
       {
-        output_path: import_zod4.z.string().optional()
+        output_path: import_zod4.z.string().optional().describe("File path to save the captured photo. If omitted, returns image data only (temp file auto-cleaned).")
       },
       async ({ output_path }) => {
         const p = platform();
@@ -1096,10 +1186,10 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "notification_send",
-      "Send OS notification",
+      "Send a native OS notification (banner/toast) to the user's desktop. Use for task completion alerts, reminders, or important status updates. The notification appears even when the terminal is not focused.",
       {
-        title: import_zod4.z.string().describe("Notification title"),
-        message: import_zod4.z.string().describe("Notification body")
+        title: import_zod4.z.string().describe("Notification title (displayed prominently)"),
+        message: import_zod4.z.string().describe("Notification body text")
       },
       async ({ title, message }) => {
         try {
@@ -1123,7 +1213,7 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "clipboard_read",
-      "Read clipboard",
+      "Read the current contents of the system clipboard (text). Use to access content the user has copied. Platform-specific: macOS (pbpaste), Windows (PowerShell), Linux (xclip).",
       {},
       async () => {
         const p = platform();
@@ -1134,8 +1224,10 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "clipboard_write",
-      "Write to clipboard",
-      { text: import_zod4.z.string() },
+      "Write text to the system clipboard, replacing its current contents. Use to prepare content for the user to paste elsewhere.",
+      {
+        text: import_zod4.z.string().describe("Text to copy to the clipboard")
+      },
       async ({ text }) => {
         const p = platform();
         const cmd = {
@@ -1149,10 +1241,15 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "screen_record",
-      "Start/stop screen recording (macOS: screencapture -v, others: ffmpeg)",
+      [
+        "Start or stop screen recording. Captures the full screen as MP4 video.",
+        "",
+        "Use action='start' to begin, action='stop' to end and save. Only one recording can be active at a time.",
+        "Platform-specific: macOS (screencapture -v), Windows/Linux (ffmpeg)."
+      ].join("\n"),
       {
-        action: import_zod4.z.enum(["start", "stop"]).describe("start: begin recording, stop: end recording"),
-        output_path: import_zod4.z.string().optional().describe("Output path (used on start, default: /tmp/junis_record_<timestamp>.mp4)")
+        action: import_zod4.z.enum(["start", "stop"]).describe("'start': begin recording, 'stop': end recording and save the file"),
+        output_path: import_zod4.z.string().optional().describe("Output file path (used with 'start'). Default: /tmp/junis_record_<timestamp>.mp4")
       },
       async ({ action, output_path }) => {
         const p = platform();
@@ -1183,7 +1280,12 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "location_get",
-      "Get current location (macOS: CoreLocation CLI, others: IP-based fallback)",
+      [
+        "Get the device's current geographic location.",
+        "",
+        "macOS: Uses CoreLocation (GPS-accurate) with IP-based fallback. Other platforms: IP-based geolocation (city-level accuracy only).",
+        "Returns latitude, longitude, and (when available) city and country."
+      ].join("\n"),
       {},
       async () => {
         const p = platform();
@@ -1210,9 +1312,9 @@ Please check if a camera is connected.` }],
     );
     server.tool(
       "audio_play",
-      "Play audio file (macOS: afplay, others: ffplay)",
+      "Play an audio file through the device's speakers. Supports MP3, WAV, AAC, and other common formats. Playback is synchronous \u2014 the tool returns after playback completes. Platform-specific: macOS (afplay), Windows/Linux (ffplay).",
       {
-        file_path: import_zod4.z.string().describe("Path to the audio file to play")
+        file_path: import_zod4.z.string().describe("Absolute path to the audio file to play")
       },
       async ({ file_path }) => {
         const p = platform();