docs: clarify CLI evaluate_script usage

Author: MukundaKatta

docs/cli.md

@@ -70,6 +70,24 @@ chrome-devtools fill "input-uid-456" "search query"
 chrome-devtools lighthouse_audit --mode snapshot
 ```
 
+**Script evaluation:**
+
+```sh
+# The JavaScript function is the first positional argument.
+chrome-devtools evaluate_script '() => document.title'
+
+# Pass snapshot UIDs through --args instead of putting them in selectors.
+chrome-devtools evaluate_script '(el) => el.innerText' --args 1_4
+
+# For longer scripts, assign the function to a shell variable first.
+script='() => {
+  return [...document.querySelectorAll("time")].map(el => el.textContent?.trim()).filter(Boolean);
+}'
+chrome-devtools evaluate_script "$script"
+```
+
+Do not invent flags like `--expression` for `evaluate_script`. The CLI expects the function as a positional argument, and single quotes are usually the safest way to preserve JavaScript syntax in the shell.
+
 ## Output format
 
 By default, the CLI outputs a human-readable summary of the tool's result. For programmatic use, you can request raw JSON:

skills/chrome-devtools-cli/SKILL.md

@@ -123,6 +123,25 @@ chrome-devtools take_snapshot # Take a text snapshot of the page from the a11y t
 chrome-devtools take_snapshot --verbose true --filePath "s.txt" # Take a verbose snapshot and save to file
 ```
 
+### `evaluate_script` quoting rules
+
+- Pass the JavaScript function as the first positional argument. Do not invent flags like `--expression`.
+- Prefer wrapping the whole function in single quotes in the shell so JavaScript parentheses and double quotes are preserved.
+- Keep the argument as a function expression such as `'() => document.title'` or `'(el) => el.innerText'`.
+- For complex scripts, write the function to a shell variable first and then pass the variable to `chrome-devtools evaluate_script`.
+
+Examples:
+
+```bash
+chrome-devtools evaluate_script '() => document.title'
+chrome-devtools evaluate_script '(el) => el.innerText' --args 1_4
+script='() => {
+  const dates = [...document.querySelectorAll("time")].map(el => el.textContent?.trim()).filter(Boolean);
+  return dates;
+}'
+chrome-devtools evaluate_script "$script"
+```
+
 ## Service Management
 
 ```bash