From d76ccf4979e48ab263bfe84be2e3a6d8a2bf6112 Mon Sep 17 00:00:00 2001
From: Levi Neely <lkn@darkstar.example.net>
Date: Sat, 14 Mar 2026 13:41:25 +0100
Subject: [PATCH] mcptools: convert all positional args to named flags

Every argument in every mcptools script is now a named flag (--mount,
--id, --agent-id, --session-id, --cwd, --child, --repo, --ticket, etc.).
No positional arguments remain. SKILL.md files updated to match.

Also updates cmd/Assist/main.go to pass --cwd flag to mount_beads.sh.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 cmd/Assist/main.go                    |  2 +-
 mcptools/add_dependency.sh            | 23 +++++++---
 mcptools/batch_create_beads.sh        | 20 +++++++--
 mcptools/claim_bead.sh                | 20 ++++-----
 mcptools/comment_bead.sh              | 21 ++++-----
 mcptools/complete_bead.sh             | 21 ++++++---
 mcptools/config_beads.sh              | 23 +++++++---
 mcptools/control_session.sh           | 20 +++++++--
 mcptools/create_bead.sh               | 16 +++----
 mcptools/create_session.sh            | 28 ++++++++++--
 mcptools/defer_bead.sh                | 29 +++++++-----
 mcptools/delete_bead.sh               | 21 ++++++---
 mcptools/fail_bead.sh                 | 21 ++++-----
 mcptools/github_to_beads.sh           | 38 +++++++++++-----
 mcptools/init_beads.sh                | 24 ++++++----
 mcptools/jira_to_beads.sh             | 49 ++++++++++++--------
 mcptools/kill_agent.sh                | 23 +++++++---
 mcptools/label_bead.sh                | 23 +++++++---
 mcptools/list_beads.sh                | 17 +++++--
 mcptools/list_ready_beads.sh          | 17 +++++--
 mcptools/mail_history.sh              | 18 ++++----
 mcptools/mail_search.sh               | 26 +++++------
 mcptools/mark_pending_approval.sh     | 20 ++++-----
 mcptools/mark_pending_review.sh       | 20 ++++-----
 mcptools/mount_beads.sh               | 16 +++++--
 mcptools/open_bead.sh                 | 21 ++++++---
 mcptools/read_bead.sh                 | 22 +++++++--
 mcptools/read_bead_comments.sh        | 19 ++++++--
 mcptools/relate_beads.sh              | 23 +++++++---
 mcptools/remove_dependency.sh         | 23 +++++++---
 mcptools/reopen_bead.sh               | 21 ++++++---
 mcptools/resume_work.sh               | 24 +++++++---
 mcptools/search_beads.sh              | 22 ++++++---
 mcptools/send_message.sh              | 28 +++++++++---
 mcptools/set_capability.sh            | 23 +++++++---
 mcptools/spawn_agent.sh               | 30 +++++++------
 mcptools/sync_beads.sh                | 18 ++++++--
 mcptools/umount_beads.sh              | 19 +++++---
 mcptools/unclaim_bead.sh              | 21 ++++++---
 mcptools/unlabel_bead.sh              | 23 +++++++---
 mcptools/unrelate_beads.sh            | 23 +++++++---
 mcptools/update_bead.sh               | 23 ++++------
 mcptools/view_denote.sh               | 17 +++++--
 skills/anvillm-communication/SKILL.md |  6 +--
 skills/anvillm-sessions/SKILL.md      | 12 ++---
 skills/beads/SKILL.md                 | 64 ++++++++++++++++-----------
 skills/github-to-beads/SKILL.md       |  2 +-
 47 files changed, 704 insertions(+), 336 deletions(-)

diff --git a/cmd/Assist/main.go b/cmd/Assist/main.go
index de3b960..fa9bee7 100644
--- a/cmd/Assist/main.go
+++ b/cmd/Assist/main.go
@@ -2651,7 +2651,7 @@ func mountProject(cwd string) (string, error) {
 	if err != nil {
 		return "", fmt.Errorf("read mount_beads.sh: %w", err)
 	}
-	cmd := exec.Command("bash", "-s", "--", cwd)
+	cmd := exec.Command("bash", "-s", "--", "--cwd", cwd)
 	cmd.Stdin = bytes.NewReader(script)
 	out, err := cmd.Output()
 	if err != nil {
diff --git a/mcptools/add_dependency.sh b/mcptools/add_dependency.sh
index a284840..c858319 100755
--- a/mcptools/add_dependency.sh
+++ b/mcptools/add_dependency.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Add a dependency (child depends on parent)
-# Usage: add_dependency.sh <mount> <child-id> <parent-id>
+# Usage: add_dependency.sh --mount <mount> --child <child-id> --parent <parent-id>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,23 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 3 ]; then
-    echo "usage: add_dependency.sh <mount> <child-id> <parent-id>" >&2
+MOUNT=""
+CHILD=""
+PARENT=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount)  MOUNT="$2";  shift 2 ;;
+        --child)  CHILD="$2";  shift 2 ;;
+        --parent) PARENT="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$CHILD" ] || [ -z "$PARENT" ]; then
+    echo "usage: add_dependency.sh --mount <mount> --child <child-id> --parent <parent-id>" >&2
     exit 1
 fi
 
-echo "dep $2 $3" | 9p write anvillm/beads/$1/ctl
-echo "$2 depends on $3"
+echo "dep $CHILD $PARENT" | 9p write anvillm/beads/$MOUNT/ctl
+echo "$CHILD depends on $PARENT"
diff --git a/mcptools/batch_create_beads.sh b/mcptools/batch_create_beads.sh
index 087aae0..2f789b7 100755
--- a/mcptools/batch_create_beads.sh
+++ b/mcptools/batch_create_beads.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Batch create beads from JSON array
-# Usage: batch_create_beads.sh <mount> <json-array>
+# Usage: batch_create_beads.sh --mount <mount> --json <json-array>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,9 +9,21 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: batch_create_beads.sh <mount> <json-array>" >&2
+MOUNT=""
+JSON=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2"; shift 2 ;;
+        --json)  JSON="$2";  shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$JSON" ]; then
+    echo "usage: batch_create_beads.sh --mount <mount> --json <json-array>" >&2
     exit 1
 fi
 
-echo "batch-create $2" | 9p write "anvillm/beads/$1/ctl"
+echo "batch-create $JSON" | 9p write "anvillm/beads/$MOUNT/ctl"
+echo "batch created beads"
diff --git a/mcptools/claim_bead.sh b/mcptools/claim_bead.sh
index 569809b..7fdc5d7 100755
--- a/mcptools/claim_bead.sh
+++ b/mcptools/claim_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Claim a bead for work
-# Usage: claim_bead.sh <mount> <bead-id> [--assignee <id>]
+# Usage: claim_bead.sh --mount <mount> --id <bead-id> [--assignee <id>]
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,24 +9,24 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: claim_bead.sh <mount> <bead-id> [--assignee <id>]" >&2
-    exit 1
-fi
-
-MOUNT="$1"
-BEAD_ID="$2"
-shift 2
-
+MOUNT=""
+BEAD_ID=""
 ASSIGNEE=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
+        --mount)    MOUNT="$2";    shift 2 ;;
+        --id)       BEAD_ID="$2";  shift 2 ;;
         --assignee) ASSIGNEE="$2"; shift 2 ;;
         *) echo "unknown argument: $1" >&2; exit 1 ;;
     esac
 done
 
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ]; then
+    echo "usage: claim_bead.sh --mount <mount> --id <bead-id> [--assignee <id>]" >&2
+    exit 1
+fi
+
 if [ -n "$ASSIGNEE" ]; then
     echo "claim $BEAD_ID $ASSIGNEE" | 9p write anvillm/beads/$MOUNT/ctl
 else
diff --git a/mcptools/comment_bead.sh b/mcptools/comment_bead.sh
index 8ecdb91..30c513e 100755
--- a/mcptools/comment_bead.sh
+++ b/mcptools/comment_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Add a comment to a bead
-# Usage: comment_bead.sh <mount> <bead-id> --text <text>
+# Usage: comment_bead.sh --mount <mount> --id <bead-id> --text <text>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,26 +9,21 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: comment_bead.sh <mount> <bead-id> --text <text>" >&2
-    exit 1
-fi
-
-MOUNT="$1"
-BEAD_ID="$2"
-shift 2
-
+MOUNT=""
+BEAD_ID=""
 TEXT=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --text) TEXT="$2"; shift 2 ;;
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        --text)  TEXT="$2";    shift 2 ;;
         *) echo "unknown argument: $1" >&2; exit 1 ;;
     esac
 done
 
-if [ -z "$TEXT" ]; then
-    echo "error: --text is required" >&2
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ] || [ -z "$TEXT" ]; then
+    echo "usage: comment_bead.sh --mount <mount> --id <bead-id> --text <text>" >&2
     exit 1
 fi
 
diff --git a/mcptools/complete_bead.sh b/mcptools/complete_bead.sh
index 0684017..b2c501d 100755
--- a/mcptools/complete_bead.sh
+++ b/mcptools/complete_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Complete a bead
-# Usage: complete_bead.sh <mount> <bead-id>
+# Usage: complete_bead.sh --mount <mount> --id <bead-id>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,21 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: complete_bead.sh <mount> <bead-id>" >&2
+MOUNT=""
+BEAD_ID=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ]; then
+    echo "usage: complete_bead.sh --mount <mount> --id <bead-id>" >&2
     exit 1
 fi
 
-echo "complete $2" | 9p write anvillm/beads/$1/ctl
-echo "completed $2"
+echo "complete $BEAD_ID" | 9p write anvillm/beads/$MOUNT/ctl
+echo "completed $BEAD_ID"
diff --git a/mcptools/config_beads.sh b/mcptools/config_beads.sh
index a450f6b..455d13b 100755
--- a/mcptools/config_beads.sh
+++ b/mcptools/config_beads.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Set a beads database configuration key
-# Usage: config_beads.sh <mount> <key> <value>
+# Usage: config_beads.sh --mount <mount> --key <key> --value <value>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,23 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 3 ]; then
-    echo "usage: config_beads.sh <mount> <key> <value>" >&2
+MOUNT=""
+KEY=""
+VALUE=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2"; shift 2 ;;
+        --key)   KEY="$2";   shift 2 ;;
+        --value) VALUE="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$KEY" ]; then
+    echo "usage: config_beads.sh --mount <mount> --key <key> --value <value>" >&2
     exit 1
 fi
 
-echo "config $2 $3" | 9p write anvillm/beads/$1/ctl
-echo "config $2 = $3"
+echo "config $KEY $VALUE" | 9p write anvillm/beads/$MOUNT/ctl
+echo "config $KEY = $VALUE"
diff --git a/mcptools/control_session.sh b/mcptools/control_session.sh
index 24dceca..a241006 100755
--- a/mcptools/control_session.sh
+++ b/mcptools/control_session.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: agents
 # description: Control a session (stop|restart|kill|refresh)
-# Usage: control_session.sh <session-id> <command>
+# Usage: control_session.sh --session-id <session-id> --command <stop|restart|kill|refresh>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,9 +9,21 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: control_session.sh <session-id> <command>" >&2
+SESSION_ID=""
+COMMAND=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --session-id) SESSION_ID="$2"; shift 2 ;;
+        --command)    COMMAND="$2";    shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$SESSION_ID" ] || [ -z "$COMMAND" ]; then
+    echo "usage: control_session.sh --session-id <session-id> --command <stop|restart|kill|refresh>" >&2
     exit 1
 fi
 
-echo "$2" | 9p write "anvillm/$1/ctl"
+echo "$COMMAND" | 9p write "anvillm/$SESSION_ID/ctl"
+echo "$COMMAND: $SESSION_ID"
diff --git a/mcptools/create_bead.sh b/mcptools/create_bead.sh
index b48b1b6..1857d2e 100755
--- a/mcptools/create_bead.sh
+++ b/mcptools/create_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Create a new bead
-# Usage: create_bead.sh <mount> --title <title> [--desc <desc>] [--parent <id>] [--no-lint] [--capability low|standard|high]
+# Usage: create_bead.sh --mount <mount> --title <title> [--desc <desc>] [--parent <id>] [--no-lint] [--capability low|standard|high]
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,14 +9,7 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: create_bead.sh <mount> --title <title> [--desc <desc>] [--parent <id>] [--no-lint] [--capability low|standard|high]" >&2
-    exit 1
-fi
-
-MOUNT="$1"
-shift
-
+MOUNT=""
 TITLE=""
 DESC=""
 PARENT=""
@@ -25,6 +18,7 @@ CAP=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
+        --mount)       MOUNT="$2";      shift 2 ;;
         --title)       TITLE="$2";      shift 2 ;;
         --desc)        DESC="$2";       shift 2 ;;
         --parent)      PARENT="$2";     shift 2 ;;
@@ -34,8 +28,8 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-if [ -z "$TITLE" ]; then
-    echo "error: --title is required" >&2
+if [ -z "$MOUNT" ] || [ -z "$TITLE" ]; then
+    echo "usage: create_bead.sh --mount <mount> --title <title> [--desc <desc>] [--parent <id>] [--no-lint] [--capability low|standard|high]" >&2
     exit 1
 fi
 
diff --git a/mcptools/create_session.sh b/mcptools/create_session.sh
index 365986f..c753bee 100755
--- a/mcptools/create_session.sh
+++ b/mcptools/create_session.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: agents
 # description: Create a new agent session
-# Usage: create_session.sh <backend> <cwd> [sandbox=<sandbox>] [model=<model>]
+# Usage: create_session.sh --backend <backend> --cwd <cwd> [--sandbox <sandbox>] [--model <model>]
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,9 +9,29 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: create_session.sh <backend> <cwd> [sandbox=<sandbox>] [model=<model>]" >&2
+BACKEND=""
+CWD=""
+SANDBOX=""
+MODEL=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --backend) BACKEND="$2"; shift 2 ;;
+        --cwd)     CWD="$2";     shift 2 ;;
+        --sandbox) SANDBOX="$2"; shift 2 ;;
+        --model)   MODEL="$2";   shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$BACKEND" ] || [ -z "$CWD" ]; then
+    echo "usage: create_session.sh --backend <backend> --cwd <cwd> [--sandbox <sandbox>] [--model <model>]" >&2
     exit 1
 fi
 
-echo "new $*" | 9p write anvillm/ctl
+CMD="new $BACKEND $CWD"
+[ -n "$SANDBOX" ] && CMD="$CMD sandbox=$SANDBOX"
+[ -n "$MODEL" ]   && CMD="$CMD model=$MODEL"
+
+echo "$CMD" | 9p write anvillm/ctl
+echo "created session: $BACKEND $CWD"
diff --git a/mcptools/defer_bead.sh b/mcptools/defer_bead.sh
index b6cb6a2..841bb1e 100755
--- a/mcptools/defer_bead.sh
+++ b/mcptools/defer_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Defer a bead, optionally until a specific time
-# Usage: defer_bead.sh <mount> <bead-id> [until <RFC3339-time>]
+# Usage: defer_bead.sh --mount <mount> --id <bead-id> [--until <RFC3339-time>]
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,18 +9,27 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: defer_bead.sh <mount> <bead-id> [until <RFC3339-time>]" >&2
+MOUNT=""
+BEAD_ID=""
+UNTIL=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        --until) UNTIL="$2";   shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ]; then
+    echo "usage: defer_bead.sh --mount <mount> --id <bead-id> [--until <RFC3339-time>]" >&2
     exit 1
 fi
 
-MOUNT="$1"
-BEAD_ID="$2"
-shift 2
-
-if [ $# -ge 2 ] && [ "$1" = "until" ]; then
-    echo "defer $BEAD_ID until $2" | 9p write anvillm/beads/$MOUNT/ctl
-    echo "deferred $BEAD_ID until $2"
+if [ -n "$UNTIL" ]; then
+    echo "defer $BEAD_ID until $UNTIL" | 9p write anvillm/beads/$MOUNT/ctl
+    echo "deferred $BEAD_ID until $UNTIL"
 else
     echo "defer $BEAD_ID" | 9p write anvillm/beads/$MOUNT/ctl
     echo "deferred $BEAD_ID"
diff --git a/mcptools/delete_bead.sh b/mcptools/delete_bead.sh
index 6bdb74a..387834c 100755
--- a/mcptools/delete_bead.sh
+++ b/mcptools/delete_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Delete a bead
-# Usage: delete_bead.sh <mount> <bead-id>
+# Usage: delete_bead.sh --mount <mount> --id <bead-id>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,21 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: delete_bead.sh <mount> <bead-id>" >&2
+MOUNT=""
+BEAD_ID=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ]; then
+    echo "usage: delete_bead.sh --mount <mount> --id <bead-id>" >&2
     exit 1
 fi
 
-echo "delete $2" | 9p write anvillm/beads/$1/ctl
-echo "deleted $2"
+echo "delete $BEAD_ID" | 9p write anvillm/beads/$MOUNT/ctl
+echo "deleted $BEAD_ID"
diff --git a/mcptools/fail_bead.sh b/mcptools/fail_bead.sh
index c898136..ad87ffa 100755
--- a/mcptools/fail_bead.sh
+++ b/mcptools/fail_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Fail a bead with reason
-# Usage: fail_bead.sh <mount> <bead-id> --reason <reason>
+# Usage: fail_bead.sh --mount <mount> --id <bead-id> --reason <reason>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,26 +9,21 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: fail_bead.sh <mount> <bead-id> --reason <reason>" >&2
-    exit 1
-fi
-
-MOUNT="$1"
-BEAD_ID="$2"
-shift 2
-
+MOUNT=""
+BEAD_ID=""
 REASON=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --reason) REASON="$2"; shift 2 ;;
+        --mount)  MOUNT="$2";   shift 2 ;;
+        --id)     BEAD_ID="$2"; shift 2 ;;
+        --reason) REASON="$2";  shift 2 ;;
         *) echo "unknown argument: $1" >&2; exit 1 ;;
     esac
 done
 
-if [ -z "$REASON" ]; then
-    echo "error: --reason is required" >&2
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ] || [ -z "$REASON" ]; then
+    echo "usage: fail_bead.sh --mount <mount> --id <bead-id> --reason <reason>" >&2
     exit 1
 fi
 
diff --git a/mcptools/github_to_beads.sh b/mcptools/github_to_beads.sh
index b3a4ab1..b889eb8 100755
--- a/mcptools/github_to_beads.sh
+++ b/mcptools/github_to_beads.sh
@@ -1,21 +1,35 @@
 #!/bin/bash
 # capabilities: beads
 # description: Import GitHub issue into beads
-# Usage: github_to_beads.sh <mount> <owner/repo> <issue-number>
+# Usage: github_to_beads.sh --mount <mount> --repo <owner/repo> --issue <issue-number>
 set -euo pipefail
 
-mount="${1:?Usage: github_to_beads.sh <mount> <owner/repo> <issue-number>}"
-repo="${2:?Usage: github_to_beads.sh <mount> <owner/repo> <issue-number>}"
-issue="${3:?Usage: github_to_beads.sh <mount> <owner/repo> <issue-number>}"
+MOUNT=""
+REPO=""
+ISSUE=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2"; shift 2 ;;
+        --repo)  REPO="$2";  shift 2 ;;
+        --issue) ISSUE="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$REPO" ] || [ -z "$ISSUE" ]; then
+    echo "usage: github_to_beads.sh --mount <mount> --repo <owner/repo> --issue <issue-number>" >&2
+    exit 1
+fi
 
 # Check if already imported
-if 9p read "anvillm/beads/$mount/list" | jq -e ".[] | select(.title | contains(\"#$issue\"))" >/dev/null 2>&1; then
-    echo "Issue #$issue already imported" >&2
+if 9p read "anvillm/beads/$MOUNT/list" | jq -e ".[] | select(.title | contains(\"#$ISSUE\"))" >/dev/null 2>&1; then
+    echo "Issue #$ISSUE already imported" >&2
     exit 0
 fi
 
 # Fetch issue data
-data=$(gh issue view "$issue" --repo "$repo" --json number,title,body,state,labels 2>/dev/null)
+data=$(gh issue view "$ISSUE" --repo "$REPO" --json number,title,body,state,labels 2>/dev/null)
 
 number=$(echo "$data" | jq -r '.number')
 title=$(echo "$data" | jq -r '.title')
@@ -39,19 +53,19 @@ fi
 bead_title="#$number: $title"
 
 # Create parent bead
-echo "new \"$bead_title\" \"$body\"" | 9p write "anvillm/beads/$mount/ctl"
+echo "new \"$bead_title\" \"$body\"" | 9p write "anvillm/beads/$MOUNT/ctl"
 
 # Get created bead ID
-bead_id=$(9p read "anvillm/beads/$mount/list" | jq -r ".[] | select(.title | contains(\"#$number\")) | .id" | head -1)
+bead_id=$(9p read "anvillm/beads/$MOUNT/list" | jq -r ".[] | select(.title | contains(\"#$number\")) | .id" | head -1)
 
 # Update issue type if not task
 if [[ "$issue_type" != "task" ]]; then
-    echo "update $bead_id issue_type $issue_type" | 9p write "anvillm/beads/$mount/ctl"
+    echo "update $bead_id issue_type $issue_type" | 9p write "anvillm/beads/$MOUNT/ctl"
 fi
 
 # Update status if closed
 if [[ "$status" == "closed" ]]; then
-    echo "update $bead_id status closed" | 9p write "anvillm/beads/$mount/ctl"
+    echo "update $bead_id status closed" | 9p write "anvillm/beads/$MOUNT/ctl"
 fi
 
 # Parse task list from body
@@ -59,7 +73,7 @@ if [[ -n "$body" ]]; then
     # Extract unchecked tasks: - [ ] Task name
     echo "$body" | grep -E '^\s*-\s+\[\s+\]' | sed -E 's/^\s*-\s+\[\s+\]\s*//' | while IFS= read -r task; do
         if [[ -n "$task" ]]; then
-            echo "new \"$task\" \"\" $bead_id" | 9p write "anvillm/beads/$mount/ctl"
+            echo "new \"$task\" \"\" $bead_id" | 9p write "anvillm/beads/$MOUNT/ctl"
         fi
     done
 fi
diff --git a/mcptools/init_beads.sh b/mcptools/init_beads.sh
index dd1ec03..5c03815 100755
--- a/mcptools/init_beads.sh
+++ b/mcptools/init_beads.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Initialize beads project with issue prefix
-# Usage: init_beads.sh <mount> [prefix]
+# Usage: init_beads.sh --mount <mount> [--prefix <prefix>]
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,13 +9,21 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 1 ]; then
-    echo "usage: init_beads.sh <mount> [prefix]" >&2
+MOUNT=""
+PREFIX="bd"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount)  MOUNT="$2";  shift 2 ;;
+        --prefix) PREFIX="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ]; then
+    echo "usage: init_beads.sh --mount <mount> [--prefix <prefix>]" >&2
     exit 1
 fi
 
-mount="$1"
-prefix="${2:-bd}"
-
-echo "init $prefix" | 9p write "anvillm/beads/$mount/ctl"
-echo "initialized $mount (prefix: $prefix)"
+echo "init $PREFIX" | 9p write "anvillm/beads/$MOUNT/ctl"
+echo "initialized $MOUNT (prefix: $PREFIX)"
diff --git a/mcptools/jira_to_beads.sh b/mcptools/jira_to_beads.sh
index 8942b56..d9af490 100755
--- a/mcptools/jira_to_beads.sh
+++ b/mcptools/jira_to_beads.sh
@@ -1,15 +1,28 @@
 #!/bin/bash
 # capabilities: beads
 # description: Import Jira ticket hierarchy into beads
-# Usage: jira_to_beads.sh <mount> <ticket-key>
+# Usage: jira_to_beads.sh --mount <mount> --ticket <ticket-key>
 set -euo pipefail
 
-mount="${1:?Usage: jira_to_beads.sh <mount> <ticket-key>}"
-ticket="${2:?Usage: jira_to_beads.sh <mount> <ticket-key>}"
+MOUNT=""
+TICKET=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount)  MOUNT="$2";  shift 2 ;;
+        --ticket) TICKET="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$TICKET" ]; then
+    echo "usage: jira_to_beads.sh --mount <mount> --ticket <ticket-key>" >&2
+    exit 1
+fi
 
 # Check if already imported
-if 9p read "anvillm/beads/$mount/list" | jq -e ".[] | select(.title | contains(\"$ticket\"))" >/dev/null 2>&1; then
-    echo "Ticket $ticket already imported" >&2
+if 9p read "anvillm/beads/$MOUNT/list" | jq -e ".[] | select(.title | contains(\"$TICKET\"))" >/dev/null 2>&1; then
+    echo "Ticket $TICKET already imported" >&2
     exit 0
 fi
 
@@ -29,45 +42,45 @@ find_root() {
 create_bead() {
     local key="$1"
     local parent_bead="${2:-}"
-    
+
     # Fetch ticket data
     local data
     data=$(jira issue view "$key" --raw 2>/dev/null)
-    
+
     local summary
     summary=$(echo "$data" | jq -r '.fields.summary')
-    
+
     local description
     description=$(echo "$data" | jq -r '.fields.description // empty')
-    
+
     # Build title: KEY: summary
     local title="$key: $summary"
-    
+
     # Create bead
     if [[ -n "$parent_bead" ]]; then
-        echo "new \"$title\" \"$description\" $parent_bead" | 9p write "anvillm/beads/$mount/ctl"
+        echo "new \"$title\" \"$description\" $parent_bead" | 9p write "anvillm/beads/$MOUNT/ctl"
     else
-        echo "new \"$title\" \"$description\"" | 9p write "anvillm/beads/$mount/ctl"
+        echo "new \"$title\" \"$description\"" | 9p write "anvillm/beads/$MOUNT/ctl"
     fi
-    
+
     # Get created bead ID
     local bead_id
-    bead_id=$(9p read "anvillm/beads/$mount/list" | jq -r ".[] | select(.title | contains(\"$key\")) | .id" | head -1)
-    
+    bead_id=$(9p read "anvillm/beads/$MOUNT/list" | jq -r ".[] | select(.title | contains(\"$key\")) | .id" | head -1)
+
     # Process children
     local children
     children=$(jira issue list --parent "$key" --plain --no-truncate 2>/dev/null | tail -n +2 | awk '{print $1}' || true)
-    
+
     if [[ -n "$children" ]]; then
         while IFS= read -r child; do
             [[ -n "$child" ]] && create_bead "$child" "$bead_id"
         done <<< "$children"
     fi
-    
+
     echo "$bead_id"
 }
 
 # Start import from root
-root=$(find_root "$ticket")
+root=$(find_root "$TICKET")
 echo "Importing from root: $root" >&2
 create_bead "$root"
diff --git a/mcptools/kill_agent.sh b/mcptools/kill_agent.sh
index dfbd652..3d31dd6 100755
--- a/mcptools/kill_agent.sh
+++ b/mcptools/kill_agent.sh
@@ -1,6 +1,7 @@
 #!/bin/bash
 # capabilities: agents
-# description: Kill agent session(s) running in the given directory: <agent-id>
+# description: Kill agent session(s) running in the given directory
+# Usage: kill_agent.sh --agent-id <agent-id>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -8,11 +9,23 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-agent_id="${1:?Usage: kill_agent.sh <agent-id>}"
+AGENT_ID=""
 
-if echo "kill" | 9p write "anvillm/$agent_id/ctl" 2>/dev/null; then
-  echo "Killed $agent_id"
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --agent-id) AGENT_ID="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$AGENT_ID" ]; then
+    echo "usage: kill_agent.sh --agent-id <agent-id>" >&2
+    exit 1
+fi
+
+if echo "kill" | 9p write "anvillm/$AGENT_ID/ctl" 2>/dev/null; then
+  echo "Killed $AGENT_ID"
 else
-  echo "No session found with id $agent_id" >&2
+  echo "No session found with id $AGENT_ID" >&2
   exit 1
 fi
diff --git a/mcptools/label_bead.sh b/mcptools/label_bead.sh
index 58c498d..d841a3a 100755
--- a/mcptools/label_bead.sh
+++ b/mcptools/label_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Add a label to a bead
-# Usage: label_bead.sh <mount> <bead-id> <label>
+# Usage: label_bead.sh --mount <mount> --id <bead-id> --label <label>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,23 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 3 ]; then
-    echo "usage: label_bead.sh <mount> <bead-id> <label>" >&2
+MOUNT=""
+BEAD_ID=""
+LABEL=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        --label) LABEL="$2";   shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ] || [ -z "$LABEL" ]; then
+    echo "usage: label_bead.sh --mount <mount> --id <bead-id> --label <label>" >&2
     exit 1
 fi
 
-echo "label $2 $3" | 9p write anvillm/beads/$1/ctl
-echo "labeled $2: $3"
+echo "label $BEAD_ID $LABEL" | 9p write anvillm/beads/$MOUNT/ctl
+echo "labeled $BEAD_ID: $LABEL"
diff --git a/mcptools/list_beads.sh b/mcptools/list_beads.sh
index 9a7f800..cbf1c12 100755
--- a/mcptools/list_beads.sh
+++ b/mcptools/list_beads.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: List all beads across all mounted projects (JSON array)
-# Usage: list_beads.sh <mount>
+# Usage: list_beads.sh --mount <mount>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,9 +9,18 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 1 ]; then
-    echo "usage: list_beads.sh <mount>" >&2
+MOUNT=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ]; then
+    echo "usage: list_beads.sh --mount <mount>" >&2
     exit 1
 fi
 
-9p read "anvillm/beads/$1/list" 2>/dev/null | jq '[.[] | {id, priority, title, status}]' || echo "[]"
+9p read "anvillm/beads/$MOUNT/list" 2>/dev/null | jq '[.[] | {id, priority, title, status}]' || echo "[]"
diff --git a/mcptools/list_ready_beads.sh b/mcptools/list_ready_beads.sh
index 4c63d4c..7b9f5a3 100755
--- a/mcptools/list_ready_beads.sh
+++ b/mcptools/list_ready_beads.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: List ready/claimable beads (JSON array)
-# Usage: list_ready_beads.sh <mount>
+# Usage: list_ready_beads.sh --mount <mount>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,9 +9,18 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 1 ]; then
-    echo "usage: list_ready_beads.sh <mount>" >&2
+MOUNT=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ]; then
+    echo "usage: list_ready_beads.sh --mount <mount>" >&2
     exit 1
 fi
 
-9p read "anvillm/beads/$1/ready" 2>/dev/null | jq '[.[] | {id, priority, title, status}]' || echo "[]"
+9p read "anvillm/beads/$MOUNT/ready" 2>/dev/null | jq '[.[] | {id, priority, title, status}]' || echo "[]"
diff --git a/mcptools/mail_history.sh b/mcptools/mail_history.sh
index 7ff368d..94cd613 100755
--- a/mcptools/mail_history.sh
+++ b/mcptools/mail_history.sh
@@ -1,24 +1,24 @@
 #!/bin/bash
 # Display message history for an agent or user.
-# Usage: mail_history.sh <agent-id|user> [--date YYYYMMdd]
+# Usage: mail_history.sh --agent-id <agent-id|user> [--date YYYYMMdd]
 set -euo pipefail
 
-AGENT_ID="${1:-}"
-if [[ -z "$AGENT_ID" ]]; then
-    echo "Usage: $0 <agent-id|user> [--date YYYYMMdd]" >&2
-    exit 1
-fi
-shift
-
+AGENT_ID=""
 DATE_FILTER=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --date) DATE_FILTER="$2"; shift 2 ;;
+        --agent-id) AGENT_ID="$2";    shift 2 ;;
+        --date)     DATE_FILTER="$2"; shift 2 ;;
         *) echo "unknown argument: $1" >&2; exit 1 ;;
     esac
 done
 
+if [[ -z "$AGENT_ID" ]]; then
+    echo "usage: mail_history.sh --agent-id <agent-id|user> [--date YYYYMMdd]" >&2
+    exit 1
+fi
+
 MAIL_DIR="$HOME/.local/share/anvillm/mail/$AGENT_ID"
 
 shopt -s nullglob
diff --git a/mcptools/mail_search.sh b/mcptools/mail_search.sh
index 6796376..17c415d 100755
--- a/mcptools/mail_search.sh
+++ b/mcptools/mail_search.sh
@@ -1,29 +1,27 @@
 #!/bin/bash
 # Search message history for an agent or user by regex pattern.
-# Usage: mail_search.sh <agent-id|user> --pattern <regex> [--date YYYYMMdd]
+# Usage: mail_search.sh --agent-id <agent-id|user> --pattern <regex> [--date YYYYMMdd]
 set -euo pipefail
 
-AGENT_ID="${1:-}"
-if [[ -z "$AGENT_ID" ]]; then
-    echo "Usage: $0 <agent-id|user> --pattern <regex> [--date YYYYMMdd]" >&2
-    exit 1
-fi
-shift
-
+AGENT_ID=""
 PATTERN=""
-DATE_FLAG=""
+DATE=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --pattern) PATTERN="$2"; shift 2 ;;
-        --date)    DATE_FLAG="--date $2"; shift 2 ;;
+        --agent-id) AGENT_ID="$2"; shift 2 ;;
+        --pattern)  PATTERN="$2";  shift 2 ;;
+        --date)     DATE="$2";     shift 2 ;;
         *) echo "unknown argument: $1" >&2; exit 1 ;;
     esac
 done
 
-if [[ -z "$PATTERN" ]]; then
-    echo "error: --pattern is required" >&2
+if [[ -z "$AGENT_ID" ]] || [[ -z "$PATTERN" ]]; then
+    echo "usage: mail_search.sh --agent-id <agent-id|user> --pattern <regex> [--date YYYYMMdd]" >&2
     exit 1
 fi
 
-bash <(9p read anvillm/tools/mail_history.sh) "$AGENT_ID" $DATE_FLAG | grep -E "$PATTERN"
+DATE_FLAG=""
+[[ -n "$DATE" ]] && DATE_FLAG="--date $DATE"
+
+bash <(9p read anvillm/tools/mail_history.sh) --agent-id "$AGENT_ID" $DATE_FLAG | grep -E "$PATTERN"
diff --git a/mcptools/mark_pending_approval.sh b/mcptools/mark_pending_approval.sh
index e70dd1a..1316080 100755
--- a/mcptools/mark_pending_approval.sh
+++ b/mcptools/mark_pending_approval.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Mark a bead as pending approval
-# Usage: mark_pending_approval.sh <mount> <bead-id> [--assignee <id>]
+# Usage: mark_pending_approval.sh --mount <mount> --id <bead-id> [--assignee <id>]
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,24 +9,24 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: mark_pending_approval.sh <mount> <bead-id> [--assignee <id>]" >&2
-    exit 1
-fi
-
-MOUNT="$1"
-BEAD_ID="$2"
-shift 2
-
+MOUNT=""
+BEAD_ID=""
 ASSIGNEE=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
+        --mount)    MOUNT="$2";    shift 2 ;;
+        --id)       BEAD_ID="$2";  shift 2 ;;
         --assignee) ASSIGNEE="$2"; shift 2 ;;
         *) echo "unknown argument: $1" >&2; exit 1 ;;
     esac
 done
 
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ]; then
+    echo "usage: mark_pending_approval.sh --mount <mount> --id <bead-id> [--assignee <id>]" >&2
+    exit 1
+fi
+
 if [ -n "$ASSIGNEE" ]; then
     echo "pending-approval $BEAD_ID $ASSIGNEE" | 9p write anvillm/beads/$MOUNT/ctl
 else
diff --git a/mcptools/mark_pending_review.sh b/mcptools/mark_pending_review.sh
index 0934b94..cd64838 100755
--- a/mcptools/mark_pending_review.sh
+++ b/mcptools/mark_pending_review.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Mark a bead as pending review
-# Usage: mark_pending_review.sh <mount> <bead-id> [--assignee <id>]
+# Usage: mark_pending_review.sh --mount <mount> --id <bead-id> [--assignee <id>]
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,24 +9,24 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: mark_pending_review.sh <mount> <bead-id> [--assignee <id>]" >&2
-    exit 1
-fi
-
-MOUNT="$1"
-BEAD_ID="$2"
-shift 2
-
+MOUNT=""
+BEAD_ID=""
 ASSIGNEE=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
+        --mount)    MOUNT="$2";    shift 2 ;;
+        --id)       BEAD_ID="$2";  shift 2 ;;
         --assignee) ASSIGNEE="$2"; shift 2 ;;
         *) echo "unknown argument: $1" >&2; exit 1 ;;
     esac
 done
 
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ]; then
+    echo "usage: mark_pending_review.sh --mount <mount> --id <bead-id> [--assignee <id>]" >&2
+    exit 1
+fi
+
 if [ -n "$ASSIGNEE" ]; then
     echo "pending-review $BEAD_ID $ASSIGNEE" | 9p write anvillm/beads/$MOUNT/ctl
 else
diff --git a/mcptools/mount_beads.sh b/mcptools/mount_beads.sh
index b70e088..02fc90e 100755
--- a/mcptools/mount_beads.sh
+++ b/mcptools/mount_beads.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Mount a beads project
-# Usage: mount_beads.sh <cwd>
+# Usage: mount_beads.sh --cwd <path>
 # Mount name is the first segment of a random UUID (8 hex chars, 32-bit entropy).
 set -euo pipefail
 
@@ -10,12 +10,20 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 1 ]; then
-    echo "usage: mount_beads.sh <cwd>" >&2
+CWD=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --cwd) CWD="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$CWD" ]; then
+    echo "usage: mount_beads.sh --cwd <path>" >&2
     exit 1
 fi
 
-CWD="$1"
 MOUNT=$(uuidgen | cut -d- -f1)
 
 echo "mount $CWD $MOUNT" | 9p write anvillm/beads/ctl
diff --git a/mcptools/open_bead.sh b/mcptools/open_bead.sh
index 275da05..ac91187 100755
--- a/mcptools/open_bead.sh
+++ b/mcptools/open_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Promote a deferred bead to open (ready for scheduling)
-# Usage: open_bead.sh <mount> <bead-id>
+# Usage: open_bead.sh --mount <mount> --id <bead-id>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,21 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: open_bead.sh <mount> <bead-id>" >&2
+MOUNT=""
+BEAD_ID=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ]; then
+    echo "usage: open_bead.sh --mount <mount> --id <bead-id>" >&2
     exit 1
 fi
 
-echo "open $2" | 9p write anvillm/beads/$1/ctl
-echo "opened $2"
+echo "open $BEAD_ID" | 9p write anvillm/beads/$MOUNT/ctl
+echo "opened $BEAD_ID"
diff --git a/mcptools/read_bead.sh b/mcptools/read_bead.sh
index 6e77b59..b940f0f 100755
--- a/mcptools/read_bead.sh
+++ b/mcptools/read_bead.sh
@@ -1,7 +1,8 @@
 #!/bin/bash
 # capabilities: beads
 # description: Read a bead property
-# Usage: read_bead.sh <mount> <bead-id> <property>
+# Usage: read_bead.sh --mount <mount> --id <bead-id> --property <property>
+# Properties: json, status, title, description, assignee, comments, labels
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,9 +10,22 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 3 ]; then
-    echo "usage: read_bead.sh <mount> <bead-id> <property>" >&2
+MOUNT=""
+BEAD_ID=""
+PROPERTY=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount)    MOUNT="$2";    shift 2 ;;
+        --id)       BEAD_ID="$2";  shift 2 ;;
+        --property) PROPERTY="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ] || [ -z "$PROPERTY" ]; then
+    echo "usage: read_bead.sh --mount <mount> --id <bead-id> --property <property>" >&2
     exit 1
 fi
 
-9p read "anvillm/beads/$1/$2/$3" 2>/dev/null || echo "Property not found: $3"
+9p read "anvillm/beads/$MOUNT/$BEAD_ID/$PROPERTY" 2>/dev/null || echo "Property not found: $PROPERTY"
diff --git a/mcptools/read_bead_comments.sh b/mcptools/read_bead_comments.sh
index 18ef45f..0305618 100755
--- a/mcptools/read_bead_comments.sh
+++ b/mcptools/read_bead_comments.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Read comments for a bead
-# Usage: read_comments.sh <mount> <bead-id>
+# Usage: read_bead_comments.sh --mount <mount> --id <bead-id>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,9 +9,20 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: read_comments.sh <mount> <bead-id>" >&2
+MOUNT=""
+BEAD_ID=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ]; then
+    echo "usage: read_bead_comments.sh --mount <mount> --id <bead-id>" >&2
     exit 1
 fi
 
-9p read "anvillm/beads/$1/$2/comments" 2>/dev/null || echo "[]"
+9p read "anvillm/beads/$MOUNT/$BEAD_ID/comments" 2>/dev/null || echo "[]"
diff --git a/mcptools/relate_beads.sh b/mcptools/relate_beads.sh
index e865644..48f2fee 100755
--- a/mcptools/relate_beads.sh
+++ b/mcptools/relate_beads.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Add a relates-to link between two beads
-# Usage: relate_beads.sh <mount> <bead-id-1> <bead-id-2>
+# Usage: relate_beads.sh --mount <mount> --bead1 <id> --bead2 <id>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,23 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 3 ]; then
-    echo "usage: relate_beads.sh <mount> <bead-id-1> <bead-id-2>" >&2
+MOUNT=""
+BEAD1=""
+BEAD2=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2"; shift 2 ;;
+        --bead1) BEAD1="$2"; shift 2 ;;
+        --bead2) BEAD2="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD1" ] || [ -z "$BEAD2" ]; then
+    echo "usage: relate_beads.sh --mount <mount> --bead1 <id> --bead2 <id>" >&2
     exit 1
 fi
 
-echo "relate $2 $3" | 9p write anvillm/beads/$1/ctl
-echo "related $2 ↔ $3"
+echo "relate $BEAD1 $BEAD2" | 9p write anvillm/beads/$MOUNT/ctl
+echo "related $BEAD1 ↔ $BEAD2"
diff --git a/mcptools/remove_dependency.sh b/mcptools/remove_dependency.sh
index 9b3034d..cadd721 100755
--- a/mcptools/remove_dependency.sh
+++ b/mcptools/remove_dependency.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Remove a dependency
-# Usage: remove_dependency.sh <mount> <child-id> <parent-id>
+# Usage: remove_dependency.sh --mount <mount> --child <child-id> --parent <parent-id>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,23 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 3 ]; then
-    echo "usage: remove_dependency.sh <mount> <child-id> <parent-id>" >&2
+MOUNT=""
+CHILD=""
+PARENT=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount)  MOUNT="$2";  shift 2 ;;
+        --child)  CHILD="$2";  shift 2 ;;
+        --parent) PARENT="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$CHILD" ] || [ -z "$PARENT" ]; then
+    echo "usage: remove_dependency.sh --mount <mount> --child <child-id> --parent <parent-id>" >&2
     exit 1
 fi
 
-echo "undep $2 $3" | 9p write anvillm/beads/$1/ctl
-echo "$2 no longer depends on $3"
+echo "undep $CHILD $PARENT" | 9p write anvillm/beads/$MOUNT/ctl
+echo "$CHILD no longer depends on $PARENT"
diff --git a/mcptools/reopen_bead.sh b/mcptools/reopen_bead.sh
index 4062cc7..3fc2f16 100755
--- a/mcptools/reopen_bead.sh
+++ b/mcptools/reopen_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Reopen a closed bead (reset to open)
-# Usage: reopen_bead.sh <mount> <bead-id>
+# Usage: reopen_bead.sh --mount <mount> --id <bead-id>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,21 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: reopen_bead.sh <mount> <bead-id>" >&2
+MOUNT=""
+BEAD_ID=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ]; then
+    echo "usage: reopen_bead.sh --mount <mount> --id <bead-id>" >&2
     exit 1
 fi
 
-echo "reopen $2" | 9p write anvillm/beads/$1/ctl
-echo "reopened $2"
+echo "reopen $BEAD_ID" | 9p write anvillm/beads/$MOUNT/ctl
+echo "reopened $BEAD_ID"
diff --git a/mcptools/resume_work.sh b/mcptools/resume_work.sh
index 8b1b35f..98f8f58 100755
--- a/mcptools/resume_work.sh
+++ b/mcptools/resume_work.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Resume work on a bead after approval/review
-# Usage: resume_work.sh <mount> <bead-id> [assignee]
+# Usage: resume_work.sh --mount <mount> --id <bead-id> [--assignee <id>]
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,17 +9,27 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: resume_work.sh <mount> <bead-id> [assignee]" >&2
+MOUNT=""
+BEAD_ID=""
+ASSIGNEE=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount)    MOUNT="$2";    shift 2 ;;
+        --id)       BEAD_ID="$2";  shift 2 ;;
+        --assignee) ASSIGNEE="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ]; then
+    echo "usage: resume_work.sh --mount <mount> --id <bead-id> [--assignee <id>]" >&2
     exit 1
 fi
 
-MOUNT="$1"
-BEAD_ID="$2"
-ASSIGNEE="${3:-}"
-
 if [ -n "$ASSIGNEE" ]; then
     echo "resume $BEAD_ID $ASSIGNEE" | 9p write anvillm/beads/$MOUNT/ctl
 else
     echo "resume $BEAD_ID" | 9p write anvillm/beads/$MOUNT/ctl
 fi
+echo "resumed $BEAD_ID${ASSIGNEE:+ → $ASSIGNEE}"
diff --git a/mcptools/search_beads.sh b/mcptools/search_beads.sh
index d12644c..6004794 100755
--- a/mcptools/search_beads.sh
+++ b/mcptools/search_beads.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Search beads by id, title, or description content
-# Usage: search_beads.sh <mount> <query>
+# Usage: search_beads.sh --mount <mount> --query <query>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,12 +9,20 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: search_beads.sh <mount> <query>" >&2
+MOUNT=""
+QUERY=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2"; shift 2 ;;
+        --query) QUERY="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$QUERY" ]; then
+    echo "usage: search_beads.sh --mount <mount> --query <query>" >&2
     exit 1
 fi
 
-mount="$1"
-query="$2"
-
-9p read "anvillm/beads/$mount/search/$query" 2>/dev/null | jq '[.[] | {id, title, status, match_in: (if .id | test("'"$query"'"; "i") then "id" elif .title | test("'"$query"'"; "i") then "title" else "description" end)}]' || echo "[]"
+9p read "anvillm/beads/$MOUNT/search/$QUERY" 2>/dev/null | jq '[.[] | {id, title, status, match_in: (if .id | test("'"$QUERY"'"; "i") then "id" elif .title | test("'"$QUERY"'"; "i") then "title" else "description" end)}]' || echo "[]"
diff --git a/mcptools/send_message.sh b/mcptools/send_message.sh
index dbfbf4f..e718821 100755
--- a/mcptools/send_message.sh
+++ b/mcptools/send_message.sh
@@ -1,9 +1,9 @@
 #!/bin/bash
 # capabilities: messaging
-# description: Send message to agent or user: TO TYPE SUBJECT BODY (FROM uses $AGENT_ID)
+# description: Send message to agent or user (FROM uses $AGENT_ID)
+# Usage: send_message.sh --to <id|user> --type <type> --subject <subject> --body <body>
 set -euo pipefail
 
-# Verify running under landrun (test filesystem restriction)
 if cat /etc/shadow >/dev/null 2>&1; then
   echo "Error: This script must be run via execute_code tool" >&2
   exit 1
@@ -15,10 +15,25 @@ if [ -z "${AGENT_ID:-}" ]; then
 fi
 from="$AGENT_ID"
 
-to="${1:?Usage: send_message <to> <type> <subject> <body>}"
-type="${2:?Usage: send_message <to> <type> <subject> <body>}"
-subject="${3:?Usage: send_message <to> <type> <subject> <body>}"
-body="${4:?Usage: send_message <to> <type> <subject> <body>}"
+to=""
+type=""
+subject=""
+body=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --to)      to="$2";      shift 2 ;;
+        --type)    type="$2";    shift 2 ;;
+        --subject) subject="$2"; shift 2 ;;
+        --body)    body="$2";    shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$to" ] || [ -z "$type" ] || [ -z "$subject" ] || [ -z "$body" ]; then
+    echo "usage: send_message.sh --to <id|user> --type <type> --subject <subject> --body <body>" >&2
+    exit 1
+fi
 
 # Validate recipient exists (allow "user" as a special recipient)
 if [ "$to" != "user" ]; then
@@ -37,3 +52,4 @@ json=$(jq -n \
   '{from: $from, to: $to, type: $type, subject: $subject, body: $body}')
 
 echo "$json" | 9p write "anvillm/${from}/mail"
+echo "sent: $type → $to"
diff --git a/mcptools/set_capability.sh b/mcptools/set_capability.sh
index 9adc1c0..e9c6ad3 100755
--- a/mcptools/set_capability.sh
+++ b/mcptools/set_capability.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Set capability level on a bead (low|standard|high)
-# Usage: set_capability.sh <mount> <bead-id> <level>
+# Usage: set_capability.sh --mount <mount> --id <bead-id> --level <low|standard|high>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,23 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 3 ]; then
-    echo "usage: set_capability.sh <mount> <bead-id> <level>" >&2
+MOUNT=""
+BEAD_ID=""
+LEVEL=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        --level) LEVEL="$2";   shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ] || [ -z "$LEVEL" ]; then
+    echo "usage: set_capability.sh --mount <mount> --id <bead-id> --level <low|standard|high>" >&2
     exit 1
 fi
 
-echo "set-capability $2 $3" | 9p write anvillm/beads/$1/ctl
-echo "capability set: $2 → $3"
+echo "set-capability $BEAD_ID $LEVEL" | 9p write anvillm/beads/$MOUNT/ctl
+echo "capability set: $BEAD_ID → $LEVEL"
diff --git a/mcptools/spawn_agent.sh b/mcptools/spawn_agent.sh
index 452f397..92f965b 100755
--- a/mcptools/spawn_agent.sh
+++ b/mcptools/spawn_agent.sh
@@ -1,29 +1,33 @@
 #!/bin/bash
 # capabilities: agents
 # description: Spawn a new agent session
-# Usage: spawn_agent.sh <agent-id> [--cwd <path>] [--prompt <initial-context>]
+# Usage: spawn_agent.sh --agent-id <agent-id> [--cwd <path>] [--prompt <initial-context>]
 set -euo pipefail
 
-agent_id="${1:?Usage: spawn_agent.sh <agent-id> [--cwd <path>] [--prompt <text>]}"
-shift
-
-cwd="$PWD"
-prompt=""
+AGENT_ID=""
+CWD="$PWD"
+PROMPT=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --cwd)    cwd="$2";    shift 2 ;;
-        --prompt) prompt="$2"; shift 2 ;;
+        --agent-id) AGENT_ID="$2"; shift 2 ;;
+        --cwd)      CWD="$2";      shift 2 ;;
+        --prompt)   PROMPT="$2";   shift 2 ;;
         *) echo "unknown argument: $1" >&2; exit 1 ;;
     esac
 done
 
-backend=$(9p read "anvillm/$agent_id/backend")
-echo "new $backend $cwd" | 9p write anvillm/ctl
+if [ -z "$AGENT_ID" ]; then
+    echo "usage: spawn_agent.sh --agent-id <agent-id> [--cwd <path>] [--prompt <text>]" >&2
+    exit 1
+fi
 
-if [ -n "$prompt" ]; then
-    session_id=$(9p read anvillm/list 2>/dev/null | awk -F'\t' -v cwd="$cwd" '$5 == cwd {print $1; exit}')
+backend=$(9p read "anvillm/$AGENT_ID/backend")
+echo "new $backend $CWD" | 9p write anvillm/ctl
+
+if [ -n "$PROMPT" ]; then
+    session_id=$(9p read anvillm/list 2>/dev/null | awk -F'\t' -v cwd="$CWD" '$5 == cwd {print $1; exit}')
     if [ -n "$session_id" ]; then
-        echo "$prompt" | 9p write "anvillm/$session_id/context"
+        echo "$PROMPT" | 9p write "anvillm/$session_id/context"
     fi
 fi
diff --git a/mcptools/sync_beads.sh b/mcptools/sync_beads.sh
index dcaf700..30b0443 100755
--- a/mcptools/sync_beads.sh
+++ b/mcptools/sync_beads.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Sync a mounted beads project
-# Usage: sync_beads.sh <mount>
+# Usage: sync_beads.sh --mount <mount>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,9 +9,19 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 1 ]; then
-    echo "usage: sync_beads.sh <mount>" >&2
+MOUNT=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ]; then
+    echo "usage: sync_beads.sh --mount <mount>" >&2
     exit 1
 fi
 
-echo "sync" | 9p write "anvillm/beads/$1/ctl"
+echo "sync" | 9p write "anvillm/beads/$MOUNT/ctl"
+echo "synced $MOUNT"
diff --git a/mcptools/umount_beads.sh b/mcptools/umount_beads.sh
index 834c6db..4261c14 100755
--- a/mcptools/umount_beads.sh
+++ b/mcptools/umount_beads.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Unmount a beads project
-# Usage: umount_beads.sh <name>
+# Usage: umount_beads.sh --mount <name>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,19 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 1 ]; then
-    echo "usage: umount_beads.sh <name>" >&2
+MOUNT=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ]; then
+    echo "usage: umount_beads.sh --mount <name>" >&2
     exit 1
 fi
 
-echo "umount $1" | 9p write anvillm/beads/ctl
-echo "unmounted $1"
+echo "umount $MOUNT" | 9p write anvillm/beads/ctl
+echo "unmounted $MOUNT"
diff --git a/mcptools/unclaim_bead.sh b/mcptools/unclaim_bead.sh
index d8cb233..9cd45c1 100755
--- a/mcptools/unclaim_bead.sh
+++ b/mcptools/unclaim_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Unclaim a bead (reset to open)
-# Usage: unclaim_bead.sh <mount> <bead-id>
+# Usage: unclaim_bead.sh --mount <mount> --id <bead-id>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,21 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 2 ]; then
-    echo "usage: unclaim_bead.sh <mount> <bead-id>" >&2
+MOUNT=""
+BEAD_ID=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ]; then
+    echo "usage: unclaim_bead.sh --mount <mount> --id <bead-id>" >&2
     exit 1
 fi
 
-echo "unclaim $2" | 9p write anvillm/beads/$1/ctl
-echo "unclaimed $2"
+echo "unclaim $BEAD_ID" | 9p write anvillm/beads/$MOUNT/ctl
+echo "unclaimed $BEAD_ID"
diff --git a/mcptools/unlabel_bead.sh b/mcptools/unlabel_bead.sh
index fdac786..9e5520d 100755
--- a/mcptools/unlabel_bead.sh
+++ b/mcptools/unlabel_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Remove a label from a bead
-# Usage: unlabel_bead.sh <mount> <bead-id> <label>
+# Usage: unlabel_bead.sh --mount <mount> --id <bead-id> --label <label>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,23 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 3 ]; then
-    echo "usage: unlabel_bead.sh <mount> <bead-id> <label>" >&2
+MOUNT=""
+BEAD_ID=""
+LABEL=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        --label) LABEL="$2";   shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ] || [ -z "$LABEL" ]; then
+    echo "usage: unlabel_bead.sh --mount <mount> --id <bead-id> --label <label>" >&2
     exit 1
 fi
 
-echo "unlabel $2 $3" | 9p write anvillm/beads/$1/ctl
-echo "unlabeled $2: $3"
+echo "unlabel $BEAD_ID $LABEL" | 9p write anvillm/beads/$MOUNT/ctl
+echo "unlabeled $BEAD_ID: $LABEL"
diff --git a/mcptools/unrelate_beads.sh b/mcptools/unrelate_beads.sh
index 26b4899..7a109a6 100755
--- a/mcptools/unrelate_beads.sh
+++ b/mcptools/unrelate_beads.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Remove a relates-to link between two beads
-# Usage: unrelate_beads.sh <mount> <bead-id-1> <bead-id-2>
+# Usage: unrelate_beads.sh --mount <mount> --bead1 <id> --bead2 <id>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,10 +9,23 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 3 ]; then
-    echo "usage: unrelate_beads.sh <mount> <bead-id-1> <bead-id-2>" >&2
+MOUNT=""
+BEAD1=""
+BEAD2=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --mount) MOUNT="$2"; shift 2 ;;
+        --bead1) BEAD1="$2"; shift 2 ;;
+        --bead2) BEAD2="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$MOUNT" ] || [ -z "$BEAD1" ] || [ -z "$BEAD2" ]; then
+    echo "usage: unrelate_beads.sh --mount <mount> --bead1 <id> --bead2 <id>" >&2
     exit 1
 fi
 
-echo "unrelate $2 $3" | 9p write anvillm/beads/$1/ctl
-echo "unrelated $2 ↔ $3"
+echo "unrelate $BEAD1 $BEAD2" | 9p write anvillm/beads/$MOUNT/ctl
+echo "unrelated $BEAD1 ↔ $BEAD2"
diff --git a/mcptools/update_bead.sh b/mcptools/update_bead.sh
index a2f8e01..bfd318c 100755
--- a/mcptools/update_bead.sh
+++ b/mcptools/update_bead.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Update a bead field directly
-# Usage: update_bead.sh <mount> <bead-id> --field <field> --value <value>
+# Usage: update_bead.sh --mount <mount> --id <bead-id> --field <field> --value <value>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,28 +9,23 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 3 ]; then
-    echo "usage: update_bead.sh <mount> <bead-id> --field <field> --value <value>" >&2
-    exit 1
-fi
-
-MOUNT="$1"
-BEAD_ID="$2"
-shift 2
-
+MOUNT=""
+BEAD_ID=""
 FIELD=""
 VALUE=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --field) FIELD="$2"; shift 2 ;;
-        --value) VALUE="$2"; shift 2 ;;
+        --mount) MOUNT="$2";   shift 2 ;;
+        --id)    BEAD_ID="$2"; shift 2 ;;
+        --field) FIELD="$2";   shift 2 ;;
+        --value) VALUE="$2";   shift 2 ;;
         *) echo "unknown argument: $1" >&2; exit 1 ;;
     esac
 done
 
-if [ -z "$FIELD" ]; then
-    echo "error: --field is required" >&2
+if [ -z "$MOUNT" ] || [ -z "$BEAD_ID" ] || [ -z "$FIELD" ]; then
+    echo "usage: update_bead.sh --mount <mount> --id <bead-id> --field <field> --value <value>" >&2
     exit 1
 fi
 
diff --git a/mcptools/view_denote.sh b/mcptools/view_denote.sh
index c545b98..12e0163 100755
--- a/mcptools/view_denote.sh
+++ b/mcptools/view_denote.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: agent-kb
 # description: View a denote document by identifier
-# Usage: view_denote.sh <denote:identifier>
+# Usage: view_denote.sh --id <denote:identifier|identifier>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,12 +9,21 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 1 ]; then
-    echo "usage: view_denote.sh <denote:identifier>" >&2
+ID=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --id) ID="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$ID" ]; then
+    echo "usage: view_denote.sh --id <denote:identifier|identifier>" >&2
     exit 1
 fi
 
-ID="${1#denote:}"
+ID="${ID#denote:}"
 FILE=$(find "$HOME/doc" -type f -name "${ID}--*" | head -1)
 
 if [ -z "$FILE" ]; then
diff --git a/skills/anvillm-communication/SKILL.md b/skills/anvillm-communication/SKILL.md
index e6ff66d..3bdbfb0 100644
--- a/skills/anvillm-communication/SKILL.md
+++ b/skills/anvillm-communication/SKILL.md
@@ -22,7 +22,7 @@ Send message:
 ```
 Tool: execute_code
 tool: send_message.sh
-args: ["<to>", "<type>", "<subject>", "<body>"]
+args: ["--to", "<id|user>", "--type", "<type>", "--subject", "<subject>", "--body", "<body>"]
 ```
 
 Check inbox:
@@ -35,7 +35,7 @@ View message history:
 ```
 Tool: execute_code
 tool: mail_history.sh
-args: ["<agent-id|user>", "--date", "YYYYMMdd"]
+args: ["--agent-id", "<agent-id|user>", "--date", "YYYYMMdd"]
 ```
 `--date` is optional. Omit to see all history.
 
@@ -43,7 +43,7 @@ Search message history:
 ```
 Tool: execute_code
 tool: mail_search.sh
-args: ["<agent-id|user>", "--pattern", "<regex>", "--date", "YYYYMMdd"]
+args: ["--agent-id", "<agent-id|user>", "--pattern", "<regex>", "--date", "YYYYMMdd"]
 ```
 `--date` is optional.
 
diff --git a/skills/anvillm-sessions/SKILL.md b/skills/anvillm-sessions/SKILL.md
index 63eb885..9e60658 100644
--- a/skills/anvillm-sessions/SKILL.md
+++ b/skills/anvillm-sessions/SKILL.md
@@ -20,21 +20,21 @@ Create session:
 ```
 Tool: execute_code
 tool: create_session.sh
-args: ["<backend>", "<cwd>", "sandbox=<sandbox>", "model=<model>"]
+args: ["--backend", "<backend>", "--cwd", "<cwd>", "--sandbox", "<sandbox>", "--model", "<model>"]
 ```
 
 Control session:
 ```
 Tool: execute_code
 tool: control_session.sh
-args: ["<session-id>", "<command>"]
+args: ["--session-id", "<session-id>", "--command", "<stop|restart|kill|refresh>"]
 ```
 
 Spawn agent (requires default sandbox):
 ```
 Tool: execute_code
 tool: spawn_agent.sh
-args: ["<agent-id>", "--cwd", "<cwd-path>", "--prompt", "<initial-context>"]
+args: ["--agent-id", "<agent-id>", "--cwd", "<cwd-path>", "--prompt", "<initial-context>"]
 sandbox: default
 ```
 `--cwd` defaults to `$PWD`. `--prompt` is optional.
@@ -43,7 +43,7 @@ Kill agent:
 ```
 Tool: execute_code
 tool: kill_agent.sh
-args: ["<cwd-path>"]
+args: ["--agent-id", "<agent-id>"]
 ```
 
 ## Backends
@@ -54,9 +54,9 @@ args: ["<cwd-path>"]
 
 ## Session Lifecycle
 
-1. Create: `create_session.sh kiro-cli /path/to/project sandbox=default`
+1. Create: `create_session.sh --backend kiro-cli --cwd /path/to/project --sandbox default`
 2. Monitor: `list_sessions.sh` (check state field)
-3. Control: `control_session.sh <id> stop|restart|kill|refresh`
+3. Control: `control_session.sh --session-id <id> --command stop|restart|kill|refresh`
 
 ## Session States
 
diff --git a/skills/beads/SKILL.md b/skills/beads/SKILL.md
index dc7e5f4..0c575e4 100644
--- a/skills/beads/SKILL.md
+++ b/skills/beads/SKILL.md
@@ -18,19 +18,19 @@ If no mount exists, create one (substitute actual path):
 ```
 Tool: execute_code
 tool: mount_beads.sh
-args: ["/path/to/project"]
+args: ["--cwd", "/path/to/project"]
 ```
 
 Initialize beads in a mount (creates .beads/):
 ```
 Tool: execute_code
 tool: init_beads.sh
-args: ["<mount>", "<prefix>"]
+args: ["--mount", "<mount>", "--prefix", "<prefix>"]
 ```
 
 ## Tools
 
-All tools require `<mount>` as first argument. Exceptions: `list_mounts.sh`, `mount_beads.sh`, `umount_beads.sh`.
+All tools require `--mount <mount>`. Exceptions: `list_mounts.sh`, `mount_beads.sh`, `umount_beads.sh`.
 
 List mounts:
 ```
@@ -42,21 +42,21 @@ List ready beads (open, unblocked):
 ```
 Tool: execute_code
 tool: list_ready_beads.sh
-args: ["<mount>"]
+args: ["--mount", "<mount>"]
 ```
 
 List all open beads (excludes closed):
 ```
 Tool: execute_code
 tool: list_beads.sh
-args: ["<mount>"]
+args: ["--mount", "<mount>"]
 ```
 
 Search beads by id, title, or description (includes closed):
 ```
 Tool: execute_code
 tool: search_beads.sh
-args: ["<mount>", "<query>"]
+args: ["--mount", "<mount>", "--query", "<query>"]
 ```
 
 **Note:** `list_beads.sh` and `list_ready_beads.sh` only return open beads. To find closed beads, use `search_beads.sh`.
@@ -65,14 +65,14 @@ Read bead JSON:
 ```
 Tool: execute_code
 tool: read_bead.sh
-args: ["<mount>", "<id>", "json"]
+args: ["--mount", "<mount>", "--id", "<id>", "--property", "json"]
 ```
 
 Read bead comments:
 ```
 Tool: execute_code
 tool: read_bead_comments.sh
-args: ["<mount>", "<id>"]
+args: ["--mount", "<mount>", "--id", "<id>"]
 ```
 
 **IMPORTANT:** When working on a bead, always check `comment_count` in the JSON output. If > 0, read comments for additional context, decisions, or blockers.
@@ -81,28 +81,28 @@ Claim bead:
 ```
 Tool: execute_code
 tool: claim_bead.sh
-args: ["<mount>", "<id>", "--assignee", "$AGENT_ID"]
+args: ["--mount", "<mount>", "--id", "<id>", "--assignee", "$AGENT_ID"]
 ```
 
 Complete bead:
 ```
 Tool: execute_code
 tool: complete_bead.sh
-args: ["<mount>", "<id>"]
+args: ["--mount", "<mount>", "--id", "<id>"]
 ```
 
 Fail bead:
 ```
 Tool: execute_code
 tool: fail_bead.sh
-args: ["<mount>", "<id>", "--reason", "<reason>"]
+args: ["--mount", "<mount>", "--id", "<id>", "--reason", "<reason>"]
 ```
 
 Create bead (starts deferred — use open_bead.sh when ready):
 ```
 Tool: execute_code
 tool: create_bead.sh
-args: ["<mount>", "--title", "<title>", "--desc", "<desc>", "--parent", "<id>"]
+args: ["--mount", "<mount>", "--title", "<title>", "--desc", "<desc>", "--parent", "<id>"]
 ```
 `--desc`, `--parent`, `--no-lint`, `--capability low|standard|high` are all optional.
 
@@ -110,7 +110,7 @@ Update bead field:
 ```
 Tool: execute_code
 tool: update_bead.sh
-args: ["<mount>", "<id>", "--field", "<field>", "--value", "<value>"]
+args: ["--mount", "<mount>", "--id", "<id>", "--field", "<field>", "--value", "<value>"]
 ```
 Valid fields: `title`, `description`, `design`, `acceptance_criteria`, `notes`, `issue_type`, `estimated_minutes`, `external_ref`, `spec_id`, `priority`, `due_at`, `work_type`. Status and assignee are managed by atomic operations only.
 
@@ -118,61 +118,75 @@ Open (promote deferred to ready):
 ```
 Tool: execute_code
 tool: open_bead.sh
-args: ["<mount>", "<id>"]
+args: ["--mount", "<mount>", "--id", "<id>"]
 ```
 
 Defer bead:
 ```
 Tool: execute_code
 tool: defer_bead.sh
-args: ["<mount>", "<id>"]
+args: ["--mount", "<mount>", "--id", "<id>"]
 ```
-Optional: append `"until", "<RFC3339-time>"` to defer until a specific time.
+Optional: append `"--until", "<RFC3339-time>"` to defer until a specific time.
 
 Reopen closed bead:
 ```
 Tool: execute_code
 tool: reopen_bead.sh
-args: ["<mount>", "<id>"]
+args: ["--mount", "<mount>", "--id", "<id>"]
 ```
 
 Relate two beads (soft link, no blocking):
 ```
 Tool: execute_code
 tool: relate_beads.sh
-args: ["<mount>", "<id-1>", "<id-2>"]
+args: ["--mount", "<mount>", "--bead1", "<id-1>", "--bead2", "<id-2>"]
 ```
 
-Add dependency:
+Add dependency (child blocked by parent):
 ```
 Tool: execute_code
 tool: add_dependency.sh
-args: ["<mount>", "<child>", "<parent>"]
+args: ["--mount", "<mount>", "--child", "<child>", "--parent", "<parent>"]
 ```
 
 Comment on bead:
 ```
 Tool: execute_code
 tool: comment_bead.sh
-args: ["<mount>", "<id>", "--text", "<text>"]
+args: ["--mount", "<mount>", "--id", "<id>", "--text", "<text>"]
 ```
 
 Label bead:
 ```
 Tool: execute_code
 tool: label_bead.sh
-args: ["<mount>", "<id>", "<label>"]
+args: ["--mount", "<mount>", "--id", "<id>", "--label", "<label>"]
 ```
 
 Delete bead:
 ```
 Tool: execute_code
 tool: delete_bead.sh
-args: ["<mount>", "<id>"]
+args: ["--mount", "<mount>", "--id", "<id>"]
 ```
 
 **Note:** Delete does not cascade. To delete a parent and all children, delete children first, then parent.
 
+Unmount project:
+```
+Tool: execute_code
+tool: umount_beads.sh
+args: ["--mount", "<mount>"]
+```
+
+Sync project:
+```
+Tool: execute_code
+tool: sync_beads.sh
+args: ["--mount", "<mount>"]
+```
+
 ## Rules
 
 - Discover your mount first using mtab
@@ -184,8 +198,8 @@ args: ["<mount>", "<id>"]
 - Comment during work (decisions, dead ends, discoveries)
 - Search past beads before starting
 - Always favor atomic actions
-	- Good: complete_bead myproj bd-123
-	- Bad: update_bead myproj bd-123 status closed
+	- Good: `complete_bead.sh --mount myproj --id bd-123`
+	- Bad: `update_bead.sh --mount myproj --id bd-123 --field status --value closed`
 
 ## Description Quality
 
diff --git a/skills/github-to-beads/SKILL.md b/skills/github-to-beads/SKILL.md
index 8cb2013..356ae67 100644
--- a/skills/github-to-beads/SKILL.md
+++ b/skills/github-to-beads/SKILL.md
@@ -13,7 +13,7 @@ Import GitHub issues into beads.
 ```
 Tool: execute_code
 tool: github_to_beads.sh
-args: ["<owner/repo>", "<issue_number>"]
+args: ["--mount", "<mount>", "--repo", "<owner/repo>", "--issue", "<issue_number>"]
 ```
 
 **What it does:**