diff --git a/src/bin/chrome-devtools.ts b/src/bin/chrome-devtools.ts
index cab71cb3a..e5da9504b 100644
--- a/src/bin/chrome-devtools.ts
+++ b/src/bin/chrome-devtools.ts
@@ -78,7 +78,43 @@ const y = yargs(hideBin(process.argv))
   .version(VERSION)
   .strict()
   .help(true)
-  .wrap(120);
+  .wrap(120)
+  .fail((msg, err) => {
+    if (msg) {
+      console.error('Error:', msg);
+      if (
+        msg.includes('Not enough non-option arguments') ||
+        msg.includes('Unknown argument') ||
+        msg.includes('Unknown arguments')
+      ) {
+        console.error('\n=========================================');
+        console.error('💡 TIP FOR AI AGENT / DEVELOPER:');
+        console.error('In the `chrome-devtools` CLI:');
+        console.error(
+          '1. Required parameters MUST be passed as positional arguments (without flags).',
+        );
+        console.error(
+          '   - INCORRECT: chrome-devtools evaluate_script --expression "() => document.title"',
+        );
+        console.error(
+          '   - CORRECT:   chrome-devtools evaluate_script "() => document.title"',
+        );
+        console.error(
+          '2. Optional parameters are passed as double-dash options/flags (e.g. --pageId 1).',
+        );
+        console.error(
+          '3. Make sure to escape quotes properly for your shell environment.',
+        );
+        console.error(
+          'Run `chrome-devtools <command> --help` to see exact positional and optional parameters.',
+        );
+        console.error('=========================================');
+      }
+    } else if (err) {
+      console.error(err);
+    }
+    process.exit(1);
+  });
 
 y.command(
   'start',