diff --git a/README.md b/README.md
index de995ad..77a3d1a 100644
--- a/README.md
+++ b/README.md
@@ -260,7 +260,7 @@ Launch Mole commands from Raycast or Alfred:
 curl -fsSL https://raw.githubusercontent.com/tw93/Mole/main/scripts/setup-quick-launchers.sh | bash
 ```
 
-Adds 5 commands: `clean`, `uninstall`, `optimize`, `analyze`, `status`.
+Adds 5 commands: `Mole Clean`, `Mole Uninstall`, `Mole Optimize`, `Mole Analyze`, `Mole Status`.
 
 ### Raycast Setup
 
@@ -271,7 +271,7 @@ After running the script, complete these steps in Raycast:
 3. Click **"Add Script Directory"** (or **"+"**)
 4. Add path: `~/Library/Application Support/Raycast/script-commands`
 5. Search in Raycast for: **"Reload Script Directories"** and run it
-6. Done! Search for `mole`, `clean`, or `optimize` to use the commands
+6. Done! Search for `mole clean`, `mole optimize`, or `mole status` to use the commands
 
 > **Note**: The script creates the commands, but Raycast still requires a one-time manual script directory setup.
 
diff --git a/scripts/setup-quick-launchers.sh b/scripts/setup-quick-launchers.sh
index 64a3784..512d9eb 100755
--- a/scripts/setup-quick-launchers.sh
+++ b/scripts/setup-quick-launchers.sh
@@ -42,8 +42,9 @@ detect_mo() {
 write_raycast_script() {
     local target="$1"
     local title="$2"
-    local mo_bin="$3"
-    local subcommand="$4"
+    local description="$3"
+    local mo_bin="$4"
+    local subcommand="$5"
 
     local cmd_for_applescript="${mo_bin//\\/\\\\}"
     cmd_for_applescript="${cmd_for_applescript//\"/\\\"}"
@@ -56,6 +57,7 @@ write_raycast_script() {
 # @raycast.title ${title}
 # @raycast.mode fullOutput
 # @raycast.packageName Mole
+# @raycast.description ${description}
 
 # Optional parameters:
 # @raycast.icon 🐹
@@ -240,11 +242,11 @@ create_raycast_commands() {
 
     log_step "Installing Raycast commands..."
     mkdir -p "$dir"
-    write_raycast_script "$dir/mole-clean.sh" "clean" "$mo_bin" "clean"
-    write_raycast_script "$dir/mole-uninstall.sh" "uninstall" "$mo_bin" "uninstall"
-    write_raycast_script "$dir/mole-optimize.sh" "optimize" "$mo_bin" "optimize"
-    write_raycast_script "$dir/mole-analyze.sh" "analyze" "$mo_bin" "analyze"
-    write_raycast_script "$dir/mole-status.sh" "status" "$mo_bin" "status"
+    write_raycast_script "$dir/mole-clean.sh" "Mole Clean" "Deep system cleanup with Mole" "$mo_bin" "clean"
+    write_raycast_script "$dir/mole-uninstall.sh" "Mole Uninstall" "Uninstall applications with Mole" "$mo_bin" "uninstall"
+    write_raycast_script "$dir/mole-optimize.sh" "Mole Optimize" "System health checks and optimization" "$mo_bin" "optimize"
+    write_raycast_script "$dir/mole-analyze.sh" "Mole Analyze" "Disk space analysis with Mole" "$mo_bin" "analyze"
+    write_raycast_script "$dir/mole-status.sh" "Mole Status" "Live system status dashboard" "$mo_bin" "status"
     log_success "Scripts ready in: $dir"
 
     log_header "Raycast Configuration"
@@ -404,11 +406,11 @@ main() {
 
     echo ""
     log_success "Done! Raycast and Alfred are ready with 5 commands:"
-    echo "  • clean, Deep system cleanup"
-    echo "  • uninstall, Remove applications"
-    echo "  • optimize, System health & tuning"
-    echo "  • analyze, Disk space explorer"
-    echo "  • status, Live system monitor"
+    echo "  • Mole Clean, Deep system cleanup"
+    echo "  • Mole Uninstall, Remove applications"
+    echo "  • Mole Optimize, System health & tuning"
+    echo "  • Mole Analyze, Disk space explorer"
+    echo "  • Mole Status, Live system monitor"
     echo ""
 }
 
diff --git a/tests/scripts.bats b/tests/scripts.bats
index 6cab9ea..f607866 100644
--- a/tests/scripts.bats
+++ b/tests/scripts.bats
@@ -72,6 +72,57 @@ setup() {
     [ "$status" -eq 0 ]
 }
 
+@test "setup-quick-launchers.sh generates Raycast scripts with discoverable metadata" {
+    local fake_bin="$HOME/fake-bin"
+    mkdir -p "$fake_bin"
+    cat > "$fake_bin/mo" <<'EOF'
+#!/bin/bash
+exit 0
+EOF
+    chmod +x "$fake_bin/mo"
+
+    run env HOME="$HOME" TERM="dumb" PATH="$fake_bin:/usr/bin:/bin:/usr/sbin:/sbin" \
+        "$PROJECT_ROOT/scripts/setup-quick-launchers.sh"
+    [ "$status" -eq 0 ]
+
+    local raycast_dir="$HOME/Library/Application Support/Raycast/script-commands"
+    [ -d "$raycast_dir" ]
+
+    local clean_script="$raycast_dir/mole-clean.sh"
+    local uninstall_script="$raycast_dir/mole-uninstall.sh"
+    local optimize_script="$raycast_dir/mole-optimize.sh"
+    local analyze_script="$raycast_dir/mole-analyze.sh"
+    local status_script="$raycast_dir/mole-status.sh"
+
+    [ -x "$clean_script" ]
+    [ -x "$uninstall_script" ]
+    [ -x "$optimize_script" ]
+    [ -x "$analyze_script" ]
+    [ -x "$status_script" ]
+
+    run grep -q '^# @raycast.title Mole Clean$' "$clean_script"
+    [ "$status" -eq 0 ]
+    run grep -q '^# @raycast.title Mole Uninstall$' "$uninstall_script"
+    [ "$status" -eq 0 ]
+    run grep -q '^# @raycast.title Mole Optimize$' "$optimize_script"
+    [ "$status" -eq 0 ]
+    run grep -q '^# @raycast.title Mole Analyze$' "$analyze_script"
+    [ "$status" -eq 0 ]
+    run grep -q '^# @raycast.title Mole Status$' "$status_script"
+    [ "$status" -eq 0 ]
+
+    run grep -q '^# @raycast.description Deep system cleanup with Mole$' "$clean_script"
+    [ "$status" -eq 0 ]
+    run grep -q '^# @raycast.description Uninstall applications with Mole$' "$uninstall_script"
+    [ "$status" -eq 0 ]
+    run grep -q '^# @raycast.description System health checks and optimization$' "$optimize_script"
+    [ "$status" -eq 0 ]
+    run grep -q '^# @raycast.description Disk space analysis with Mole$' "$analyze_script"
+    [ "$status" -eq 0 ]
+    run grep -q '^# @raycast.description Live system status dashboard$' "$status_script"
+    [ "$status" -eq 0 ]
+}
+
 @test "install.sh supports dev branch installs" {
     run bash -c "grep -q 'refs/heads/dev.tar.gz' '$PROJECT_ROOT/install.sh'"
     [ "$status" -eq 0 ]