diff --git a/site/src/content/docs/setup/cli.mdx b/site/src/content/docs/setup/cli.mdx
index 11a3cb97..407ab843 100644
--- a/site/src/content/docs/setup/cli.mdx
+++ b/site/src/content/docs/setup/cli.mdx
@@ -154,13 +154,13 @@ Options:
 
 ### `disable [path]`
 
-Set `queueStatus` to `disabled` (or `paused`) on every matched ADO definition.
+Set `queueStatus` to `disabled` (or `paused`) on every matched ADO definition. Disabled definitions reject all queue requests; paused definitions queue scheduled runs but hold them without executing.
 
 Options:
 
-- `--paused` -- use `queueStatus: paused` instead of `disabled`; paused definitions still queue scheduled runs but hold the queue, while disabled definitions reject all queue requests
+- `--paused` -- set `queueStatus` to `paused` instead of `disabled`
 - `--org`, `--project`, `--pat` -- same as `enable`
-- `--dry-run` -- print the planned transitions without calling the ADO API
+- `--dry-run` -- preview the planned transitions without calling the ADO API
 
 ### `remove [path]`
 
@@ -168,9 +168,9 @@ Options:
 
 Options:
 
-- `--yes` -- required for bulk deletes and for any delete in a non-tty context
+- `--yes` -- required for bulk deletes (more than one match) and for any delete in a non-tty context
 - `--org`, `--project`, `--pat` -- same as `enable`
-- `--dry-run` -- print the planned deletions without calling the ADO API
+- `--dry-run` -- preview the planned deletions without calling the ADO API
 
 ### `list [path]`
 
@@ -202,12 +202,12 @@ ado-aw run [path] [--wait] [--parameters key=value]
 Options:
 
 - `--branch <ref>` -- source branch to queue (defaults to the definition's `defaultBranch`)
-- `--parameters <k=v>` -- ADO `templateParameters` as `key=value` pairs; repeatable and/or comma-separated. Values must not contain commas — use one `--parameters` flag per pair when values contain commas.
-- `--wait` -- poll each queued build to completion before exiting
-- `--poll-interval <secs>` -- polling interval when `--wait` is set (default: `10`)
-- `--timeout <secs>` -- maximum wait time when `--wait` is set (default: `1800`)
+- `--parameters <k=v>` -- ADO `templateParameters` as `key=value` pairs; repeatable and/or comma-separated. Values must not contain commas — use one `--parameters` flag per pair when values contain commas
+- `--wait` -- poll each queued build to completion before exiting; aggregate result determines the exit code
+- `--poll-interval <secs>` -- seconds between polls when `--wait` is set (default: `10`)
+- `--timeout <secs>` -- maximum seconds to wait when `--wait` is set (default: `1800`)
 - `--org`, `--project`, `--pat` -- same as `enable`
-- `--dry-run` -- print the planned queue body without calling the ADO API
+- `--dry-run` -- preview the planned queue body without calling the ADO API
 
 ## Internal / pipeline runtime commands
 
@@ -215,7 +215,7 @@ These commands are used by the compiled pipeline itself and are not typically ca
 
 ### `mcp <output_directory> <bounding_directory>`
 
-Run SafeOutputs as a stdio MCP server (used by Stage 1).
+Run SafeOutputs as a stdio MCP server (used by Stage 1). The `<bounding_directory>` guards against directory traversal attacks by ensuring the agent cannot influence folders outside this path.
 
 ```bash
 ado-aw mcp <output_directory> <bounding_directory> [--enabled-tools <name>]
@@ -223,11 +223,11 @@ ado-aw mcp <output_directory> <bounding_directory> [--enabled-tools <name>]
 
 Options:
 
-- `--enabled-tools <name>` -- limit the server to specific tools; repeat to allow more than one
+- `--enabled-tools <name>` -- only expose these safe output tools; repeat to allow more than one. If omitted, all tools are exposed
 
 ### `mcp-http <output_directory> <bounding_directory>`
 
-Run SafeOutputs as an HTTP MCP server (for MCPG integration).
+Run SafeOutputs as an HTTP MCP server (for MCPG integration). The `<bounding_directory>` guards against directory traversal attacks.
 
 ```bash
 ado-aw mcp-http <output_directory> <bounding_directory> [options]
@@ -236,8 +236,8 @@ ado-aw mcp-http <output_directory> <bounding_directory> [options]
 Options:
 
 - `--port <port>` -- port to listen on (default: `8100`)
-- `--api-key <key>` -- API key for authentication (auto-generated if not provided)
-- `--enabled-tools <name>` -- limit the server to specific tools; repeat to allow more than one
+- `--api-key <key>` -- API key for authentication (if not provided, one is generated)
+- `--enabled-tools <name>` -- only expose these safe output tools; repeat to allow more than one. If omitted, all tools are exposed
 
 ### `execute`