From 46d81b4162003c43156176d94daea27f32932dc5 Mon Sep 17 00:00:00 2001
From: bendtherules <abhasbhattacharya2@gmail.com>
Date: Mon, 23 Mar 2026 10:24:49 +0530
Subject: [PATCH] feat(tools): enhance CLI tool descriptions and add remote
 handling option
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Updated `cleanupTool` description to include detailed usage and arguments.
- Added optional `noRemote` flag to `cleanupTool` for local‑only tag deletion.
- Adjusted remote handling logic to respect the new `noRemote` flag.
- Expanded `closeTool` description with clear argument documentation.
- Expanded `openTool` description with detailed argument documentation.
---
 src/tools/cleanup.ts | 20 ++++++++++++--------
 src/tools/close.ts   |  8 ++++++--
 src/tools/open.ts    |  6 +++++-
 3 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/src/tools/cleanup.ts b/src/tools/cleanup.ts
index 740ae56..89994bd 100644
--- a/src/tools/cleanup.ts
+++ b/src/tools/cleanup.ts
@@ -8,8 +8,11 @@ import { cleanupMultiModel } from "../core/cleanup";
  * Used to clean up recovery tags created by the close command.
  */
 export const cleanupTool = tool({
-  description:
-    "Delete all archive tags from local and optionally remote repository",
+  description: `Delete all archive tags from the local repository and, optionally, from a remote.
+
+Arguments:
+-\`remote\` (string, optional): Specify a remote name to which deletions should be pushed. If omitted, the first available remote is used.
+- \`noRemote\` (boolean, optional): When true, only delete local tags and do not push deletions to any remote.`,
   args: {
     remote: tool.schema
       .union([
@@ -17,21 +20,22 @@ export const cleanupTool = tool({
           .string()
           .describe(
             "Remote name to push deletions to. Error if doesn't exist.",
-          ),
-        tool.schema
-          .literal(false)
-          .describe("Only delete local tags, don't push to remote."),
+          )
       ])
       .optional()
       .describe(
-        "Remote handling: string=specific remote, false=local-only, undefined=first available remote",
+        "Remote handling: string=specific remote, undefined=first available remote",
       ),
+    noRemote: tool.schema
+      .literal(true)
+      .describe("Only delete local tags, don't push to remote.")
+      .optional(),
   },
   async execute(args, _context) {
     // In plugin mode, we skip confirmation (force=true)
     const result = await cleanupMultiModel({
       force: true,
-      remote: args.remote,
+      remote: args.noRemote ? false : args.remote,
     });
 
     if (!result.success) {
diff --git a/src/tools/close.ts b/src/tools/close.ts
index 5b239c9..439fad9 100644
--- a/src/tools/close.ts
+++ b/src/tools/close.ts
@@ -8,8 +8,12 @@ import { closeMultiModel } from "../core/close";
  * creates archive tags, and deletes associated branches.
  */
 export const closeTool = tool({
-  description:
-    "Close a multi-model tmux session and optionally cleanup worktrees and branches",
+  description: `Close a multi-model tmux session and optionally clean up worktrees and branches.
+
+Arguments:
+- \`sessionName\` (string, required): tmux session name to close.
+- \`cleanupWorktrees\` (boolean, optional, default: true): Whether to remove worktrees and delete branches.
+- \`createArchiveTags\` (boolean, optional, default: true): Whether to create archive tags before deleting branches.`,
   args: {
     sessionName: tool.schema
       .string()
diff --git a/src/tools/open.ts b/src/tools/open.ts
index a0ab3b1..0952c96 100644
--- a/src/tools/open.ts
+++ b/src/tools/open.ts
@@ -9,7 +9,11 @@ import { getBinaryName } from "../core/utils";
  * Returns instructions for attaching to and cleaning up the session.
  */
 export const openTool = tool({
-  description: "Launch multiple OpenCode models in tmux",
+  description: `Launch multiple OpenCode models in tmux.
+
+Arguments:
+- \`sessionName\` (string, required): tmux session name to create.
+- \`models\` (array of strings, required): one or more OpenCode model IDs to launch.`,
   args: {
     sessionName: tool.schema
       .string()