@kanbodev/mcp 1.0.4 → 1.1.0

package/dist/index.js

@@ -15479,13 +15479,13 @@ function startCallbackServer(port, expectedState, timeoutMs = 120000) {
       }
       if (error2) {
         res.writeHead(400, { "Content-Type": "text/html" });
-        res.end(errorHtml(decodeURIComponent(error2)));
+        res.end(errorHtml(error2));
         if (!resolved) {
           resolved = true;
           server.close();
           resolve({
             success: false,
-            error: decodeURIComponent(error2)
+            error: error2
           });
         }
         return;
@@ -15628,11 +15628,161 @@ var init_config = __esm(() => {
   CONFIG_PATH = path2.join(CONFIG_DIR, "config.json");
 });
 
+// src/cli/register.ts
+import * as fs3 from "node:fs";
+import * as path3 from "node:path";
+import * as os3 from "node:os";
+import { execFileSync } from "node:child_process";
+function getVscodeMcpPath() {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    return path3.join(os3.homedir(), "Library", "Application Support", "Code", "User", "mcp.json");
+  }
+  if (platform === "win32") {
+    return path3.join(process.env.APPDATA || "", "Code", "User", "mcp.json");
+  }
+  return path3.join(os3.homedir(), ".config", "Code", "User", "mcp.json");
+}
+function getCursorMcpPath() {
+  return path3.join(os3.homedir(), ".cursor", "mcp.json");
+}
+function getClaudeDesktopMcpPath() {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    return path3.join(os3.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  if (platform === "win32") {
+    return path3.join(process.env.APPDATA || "", "Claude", "claude_desktop_config.json");
+  }
+  return path3.join(os3.homedir(), ".config", "Claude", "claude_desktop_config.json");
+}
+function registerInConfigFile(configPath, hostName, serversKey = "servers") {
+  try {
+    const parentDir = path3.dirname(configPath);
+    if (!fs3.existsSync(parentDir)) {
+      return { host: hostName, success: false, message: `${hostName} not detected` };
+    }
+    let config3 = {};
+    if (fs3.existsSync(configPath)) {
+      const content = fs3.readFileSync(configPath, "utf-8");
+      config3 = JSON.parse(content);
+    }
+    const servers = config3[serversKey] || {};
+    if (servers[SERVER_NAME]) {
+      return {
+        host: hostName,
+        success: true,
+        alreadyRegistered: true,
+        message: `Already registered in ${hostName}`
+      };
+    }
+    servers[SERVER_NAME] = MCP_SERVER_ENTRY;
+    config3[serversKey] = servers;
+    fs3.writeFileSync(configPath, JSON.stringify(config3, null, 2) + `
+`, "utf-8");
+    return {
+      host: hostName,
+      success: true,
+      message: `Registered in ${hostName}`
+    };
+  } catch (error2) {
+    const msg = error2 instanceof Error ? error2.message : "Unknown error";
+    return { host: hostName, success: false, message: `Failed to register in ${hostName}: ${msg}` };
+  }
+}
+function isClaudeCliAvailable() {
+  try {
+    execFileSync("claude", ["--version"], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function registerWithClaudeCli() {
+  const hostName = "Claude Code CLI";
+  try {
+    if (!isClaudeCliAvailable()) {
+      return { host: hostName, success: false, message: "Claude Code CLI not detected" };
+    }
+    execFileSync("claude", ["mcp", "add", SERVER_NAME, "--", "npx", "@kanbodev/mcp"], {
+      stdio: "pipe"
+    });
+    return { host: hostName, success: true, message: "Registered via Claude Code CLI" };
+  } catch (error2) {
+    const msg = error2 instanceof Error ? error2.message : "Unknown error";
+    if (msg.includes("already exists")) {
+      return { host: hostName, success: true, alreadyRegistered: true, message: "Already registered in Claude Code CLI" };
+    }
+    return { host: hostName, success: false, message: `Failed to register via Claude Code CLI: ${msg}` };
+  }
+}
+function registerMcpServer() {
+  const results = [];
+  results.push(registerInConfigFile(getVscodeMcpPath(), "VS Code"));
+  results.push(registerInConfigFile(getCursorMcpPath(), "Cursor"));
+  results.push(registerInConfigFile(getClaudeDesktopMcpPath(), "Claude Desktop", "mcpServers"));
+  results.push(registerWithClaudeCli());
+  return results;
+}
+function printRegistrationResults(results) {
+  const registered = results.filter((r) => r.success && !r.alreadyRegistered);
+  const alreadyRegistered = results.filter((r) => r.success && r.alreadyRegistered);
+  const anySuccess = results.some((r) => r.success);
+  if (registered.length > 0) {
+    console.log("  MCP server registered with:");
+    for (const r of registered) {
+      console.log(`    ✓ ${r.message}`);
+    }
+  }
+  if (alreadyRegistered.length > 0) {
+    for (const r of alreadyRegistered) {
+      console.log(`    · ${r.message}`);
+    }
+  }
+  if (registered.length > 0) {
+    console.log("");
+    console.log("  Reload your editor to activate the Kanbo MCP server.");
+  }
+  if (!anySuccess) {
+    printManualInstructions();
+  }
+  return anySuccess;
+}
+function printManualInstructions() {
+  console.log("  To register the MCP server manually, add this to your mcp.json:");
+  console.log("");
+  console.log("    {");
+  console.log('      "servers": {');
+  console.log('        "kanbodev": {');
+  console.log('          "type": "stdio",');
+  console.log('          "command": "npx",');
+  console.log('          "args": ["@kanbodev/mcp"]');
+  console.log("        }");
+  console.log("      }");
+  console.log("    }");
+  console.log("");
+  console.log("  Config file locations:");
+  console.log(`    VS Code:        ${getVscodeMcpPath()}`);
+  console.log(`    Cursor:         ${getCursorMcpPath()}`);
+  console.log(`    Claude Desktop: ${getClaudeDesktopMcpPath()}`);
+  console.log("");
+  console.log("  Or register via Claude Code CLI:");
+  console.log("    claude mcp add kanbodev -- npx @kanbodev/mcp");
+}
+var SERVER_NAME = "kanbodev", MCP_SERVER_ENTRY;
+var init_register = __esm(() => {
+  MCP_SERVER_ENTRY = {
+    type: "stdio",
+    command: "npx",
+    args: ["@kanbodev/mcp"]
+  };
+});
+
 // node_modules/is-docker/index.js
-import fs3 from "node:fs";
+import fs4 from "node:fs";
 function hasDockerEnv() {
   try {
-    fs3.statSync("/.dockerenv");
+    fs4.statSync("/.dockerenv");
     return true;
   } catch {
     return false;
@@ -15640,7 +15790,7 @@ function hasDockerEnv() {
 }
 function hasDockerCGroup() {
   try {
-    return fs3.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
+    return fs4.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
   } catch {
     return false;
   }
@@ -15655,7 +15805,7 @@ var isDockerCached;
 var init_is_docker = () => {};
 
 // node_modules/is-inside-container/index.js
-import fs4 from "node:fs";
+import fs5 from "node:fs";
 function isInsideContainer() {
   if (cachedResult === undefined) {
     cachedResult = hasContainerEnv() || isDocker();
@@ -15664,7 +15814,7 @@ function isInsideContainer() {
 }
 var cachedResult, hasContainerEnv = () => {
   try {
-    fs4.statSync("/run/.containerenv");
+    fs5.statSync("/run/.containerenv");
     return true;
   } catch {
     return false;
@@ -15676,20 +15826,20 @@ var init_is_inside_container = __esm(() => {
 
 // node_modules/is-wsl/index.js
 import process4 from "node:process";
-import os3 from "node:os";
-import fs5 from "node:fs";
+import os4 from "node:os";
+import fs6 from "node:fs";
 var isWsl = () => {
   if (process4.platform !== "linux") {
     return false;
   }
-  if (os3.release().toLowerCase().includes("microsoft")) {
+  if (os4.release().toLowerCase().includes("microsoft")) {
     if (isInsideContainer()) {
       return false;
     }
     return true;
   }
   try {
-    return fs5.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft") ? !isInsideContainer() : false;
+    return fs6.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft") ? !isInsideContainer() : false;
   } catch {
     return false;
   }
@@ -15749,7 +15899,7 @@ function parseMountPointFromConfig(content) {
 // node_modules/wsl-utils/index.js
 import { promisify as promisify2 } from "node:util";
 import childProcess2 from "node:child_process";
-import fs6, { constants as fsConstants } from "node:fs/promises";
+import fs7, { constants as fsConstants } from "node:fs/promises";
 var execFile2, wslDrivesMountPoint, powerShellPathFromWsl = async () => {
   const mountPoint = await wslDrivesMountPoint();
   return `${mountPoint}c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe`;
@@ -15757,7 +15907,7 @@ var execFile2, wslDrivesMountPoint, powerShellPathFromWsl = async () => {
   canAccessPowerShellPromise ??= (async () => {
     try {
       const psPath = await powerShellPath2();
-      await fs6.access(psPath, fsConstants.X_OK);
+      await fs7.access(psPath, fsConstants.X_OK);
       return true;
     } catch {
       return false;
@@ -15769,15 +15919,15 @@ var execFile2, wslDrivesMountPoint, powerShellPathFromWsl = async () => {
   const command = String.raw`(Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\Shell\Associations\UrlAssociations\http\UserChoice").ProgId`;
   const { stdout } = await executePowerShell(command, { powerShellPath: psPath });
   return stdout.trim();
-}, convertWslPathToWindows = async (path3) => {
-  if (/^[a-z]+:\/\//i.test(path3)) {
-    return path3;
+}, convertWslPathToWindows = async (path4) => {
+  if (/^[a-z]+:\/\//i.test(path4)) {
+    return path4;
   }
   try {
-    const { stdout } = await execFile2("wslpath", ["-aw", path3], { encoding: "utf8" });
+    const { stdout } = await execFile2("wslpath", ["-aw", path4], { encoding: "utf8" });
     return stdout.trim();
   } catch {
-    return path3;
+    return path4;
   }
 };
 var init_wsl_utils = __esm(() => {
@@ -15795,13 +15945,13 @@ var init_wsl_utils = __esm(() => {
       const configFilePath = "/etc/wsl.conf";
       let isConfigFileExists = false;
       try {
-        await fs6.access(configFilePath, fsConstants.F_OK);
+        await fs7.access(configFilePath, fsConstants.F_OK);
         isConfigFileExists = true;
       } catch {}
       if (!isConfigFileExists) {
         return defaultMountPoint;
       }
-      const configContent = await fs6.readFile(configFilePath, { encoding: "utf8" });
+      const configContent = await fs7.readFile(configFilePath, { encoding: "utf8" });
       const parsedMountPoint = parseMountPointFromConfig(configContent);
       if (parsedMountPoint === undefined) {
         return defaultMountPoint;
@@ -15856,7 +16006,7 @@ var init_default_browser_id = __esm(() => {
 // node_modules/run-applescript/index.js
 import process7 from "node:process";
 import { promisify as promisify4 } from "node:util";
-import { execFile as execFile4, execFileSync } from "node:child_process";
+import { execFile as execFile4, execFileSync as execFileSync2 } from "node:child_process";
 async function runAppleScript(script, { humanReadableOutput = true, signal } = {}) {
   if (process7.platform !== "darwin") {
     throw new Error("macOS only");
@@ -15976,10 +16126,10 @@ __export(exports_open, {
   apps: () => apps
 });
 import process10 from "node:process";
-import path3 from "node:path";
+import path4 from "node:path";
 import { fileURLToPath } from "node:url";
 import childProcess3 from "node:child_process";
-import fs7, { constants as fsConstants2 } from "node:fs/promises";
+import fs8, { constants as fsConstants2 } from "node:fs/promises";
 function detectArchBinary(binary) {
   if (typeof binary === "string" || Array.isArray(binary)) {
     return binary;
@@ -16143,7 +16293,7 @@ var fallbackAttemptSymbol, __dirname2, localXdgOpenPath, platform, arch, tryEach
       const isBundled = !__dirname2 || __dirname2 === "/";
       let exeLocalXdgOpen = false;
       try {
-        await fs7.access(localXdgOpenPath, fsConstants2.X_OK);
+        await fs8.access(localXdgOpenPath, fsConstants2.X_OK);
         exeLocalXdgOpen = true;
       } catch {}
       const useSystemXdgOpen = process10.versions.electron ?? (platform === "android" || isBundled || !exeLocalXdgOpen);
@@ -16231,8 +16381,8 @@ var init_open = __esm(() => {
   init_is_inside_container();
   init_is_in_ssh();
   fallbackAttemptSymbol = Symbol("fallbackAttempt");
-  __dirname2 = import.meta.url ? path3.dirname(fileURLToPath(import.meta.url)) : "";
-  localXdgOpenPath = path3.join(__dirname2, "xdg-open");
+  __dirname2 = import.meta.url ? path4.dirname(fileURLToPath(import.meta.url)) : "";
+  localXdgOpenPath = path4.join(__dirname2, "xdg-open");
   ({ platform, arch } = process10);
   apps = {
     browser: "browser",
@@ -16284,6 +16434,7 @@ __export(exports_login, {
   login: () => login
 });
 import * as crypto2 from "node:crypto";
+import { createRequire as createRequire2 } from "node:module";
 async function login() {
   console.log(`
   Kanbo CLI Login
@@ -16328,7 +16479,15 @@ async function login() {
     console.log("  Could not open browser automatically.");
     console.log("  Please copy the URL above and paste it in your browser.");
   }
-  const result = await startCallbackServer(port, state);
+  let result;
+  try {
+    result = await startCallbackServer(port, state);
+  } catch (error2) {
+    console.log("");
+    console.error(`  Error: Failed to start callback server.`);
+    console.error(`  ${error2 instanceof Error ? error2.message : "Unknown error"}`);
+    process.exit(1);
+  }
   if (!result.success) {
     console.log("");
     console.error(`  Authentication failed: ${result.error}`);
@@ -16357,17 +16516,20 @@ async function login() {
   console.log("");
   console.log(`  Config saved to: ${getConfigPath()}`);
   console.log("");
-  console.log("  You can now use Kanbo MCP server. Run:");
-  console.log("    kanbo-mcp");
+  const registrationResults = registerMcpServer();
+  printRegistrationResults(registrationResults);
   console.log("");
 }
-var KANBO_WEB_URL, DEFAULT_API_URL, PORT_RANGE, CLI_VERSION = "1.0.0";
+var KANBO_WEB_URL, DEFAULT_API_URL, PORT_RANGE, require2, CLI_VERSION;
 var init_login = __esm(() => {
   init_callback_server();
   init_config();
+  init_register();
   KANBO_WEB_URL = process.env.KANBO_WEB_URL || "https://kanbo.dev";
   DEFAULT_API_URL = process.env.KANBO_API_URL || "https://api.kanbo.dev";
   PORT_RANGE = { start: 9876, end: 9899 };
+  require2 = createRequire2(import.meta.url);
+  CLI_VERSION = require2("../../package.json").version;
 });
 
 // src/cli/logout.ts
@@ -16450,6 +16612,37 @@ var init_whoami = __esm(() => {
   init_config();
 });
 
+// src/cli/install.ts
+var exports_install = {};
+__export(exports_install, {
+  install: () => install
+});
+async function install() {
+  console.log(`
+  Kanbo MCP — Install
+`);
+  const config3 = loadConfig();
+  if (!config3) {
+    console.log("  You are not logged in. Please authenticate first:");
+    console.log("    npx @kanbodev/mcp login");
+    console.log("");
+    console.log("  Or register the MCP server manually:");
+    console.log("");
+    printManualInstructions();
+    console.log("");
+    return;
+  }
+  console.log(`  Logged in as ${config3.userEmail} (${config3.orgName})`);
+  console.log("");
+  const results = registerMcpServer();
+  printRegistrationResults(results);
+  console.log("");
+}
+var init_install = __esm(() => {
+  init_config();
+  init_register();
+});
+
 // src/config/constants.ts
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -24821,18 +25014,18 @@ function formatToolResult(result) {
 var listProjectsTool = {
   tool: {
     name: "list_projects",
-    description: "List all projects the user has access to in the current organization",
+    description: "List all projects in the current organization. Returns project IDs needed by most other tools. Call set_organization first if you have multiple orgs.",
     inputSchema: {
       type: "object",
       properties: {
         includeArchived: {
           type: "boolean",
-          description: "Include archived projects (default: false)",
+          description: "Include archived projects in results (default: false)",
           default: false
         },
         search: {
           type: "string",
-          description: "Filter by project name"
+          description: "Filter by project name substring (optional)"
         }
       }
     }
@@ -24853,13 +25046,13 @@ var listProjectsTool = {
 var getProjectTool = {
   tool: {
     name: "get_project",
-    description: "Get detailed information about a specific project including settings and workflow",
+    description: "Get detailed information about a specific project including settings, workflow configuration, and metadata. Use list_projects to find the project ID.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID (format: prj_xxxxx)"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         }
       },
       required: ["projectId"]
@@ -24878,13 +25071,13 @@ var getProjectTool = {
 var getProjectBySlugTool = {
   tool: {
     name: "get_project_by_slug",
-    description: 'Get a project by its URL slug (e.g., "my-project")',
+    description: 'Get a project by its URL slug (e.g., "my-project"). Useful when you know the project name but not its ID.',
     inputSchema: {
       type: "object",
       properties: {
         slug: {
           type: "string",
-          description: "Project slug from the URL"
+          description: 'Project slug from the URL (lowercase-kebab-case, e.g., "my-project")'
         }
       },
       required: ["slug"]
@@ -24903,25 +25096,25 @@ var getProjectBySlugTool = {
 var createProjectTool = {
   tool: {
     name: "create_project",
-    description: "Create a new project in the current organization. Requires an initial (3-6 uppercase letters) used as ticket key prefix.",
+    description: "Create a new project in the current organization. Requires an initial (3-6 uppercase letters) used as ticket key prefix (e.g., tickets become PROJ-1, PROJ-2). The initial cannot be changed after creation.",
     inputSchema: {
       type: "object",
       properties: {
         name: {
           type: "string",
-          description: "Project name"
+          description: "Project name (1-100 chars)"
         },
         initial: {
           type: "string",
-          description: 'Project initial (3-6 uppercase letters, e.g., "PROJ"). Used as ticket key prefix and cannot be changed later.'
+          description: 'Project initial (3-6 uppercase letters, e.g., "PROJ"). Used as ticket key prefix (PROJ-1, PROJ-2). Cannot be changed later.'
         },
         description: {
           type: "string",
-          description: "Project description (optional)"
+          description: "Project description (optional, plain text)"
         },
         color: {
           type: "string",
-          description: 'Project color as hex (e.g., "#FF5733", optional)'
+          description: 'Project theme color as hex (e.g., "#FF5733", optional)'
         }
       },
       required: ["name", "initial"]
@@ -24945,25 +25138,25 @@ var createProjectTool = {
 var updateProjectTool = {
   tool: {
     name: "update_project",
-    description: "Update project details (name, description, color). Requires settings access.",
+    description: "Update project details. Only pass fields you want to change — omitted fields are not modified. Requires project admin or owner role.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         },
         name: {
           type: "string",
-          description: "New project name"
+          description: "New project name (1-100 chars)"
         },
         description: {
           type: "string",
-          description: "New project description"
+          description: "New project description (plain text)"
         },
         color: {
           type: "string",
-          description: 'New project color as hex (e.g., "#FF5733")'
+          description: 'New project theme color as hex (e.g., "#FF5733")'
         }
       },
       required: ["projectId"]
@@ -24989,13 +25182,13 @@ var updateProjectTool = {
 var deleteProjectTool = {
   tool: {
     name: "delete_project",
-    description: "Soft delete a project (can be restored). Requires delete access.",
+    description: "Soft-delete a project. The project can be restored later. All tickets and data are preserved. Requires project owner role.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID to delete"
+          description: "Project ID to delete (format: prj_xxxxx)"
         }
       },
       required: ["projectId"]
@@ -25014,13 +25207,13 @@ var deleteProjectTool = {
 var archiveProjectTool = {
   tool: {
     name: "archive_project",
-    description: "Archive a project. Archived projects are hidden from lists but can be unarchived.",
+    description: "Archive a project. Archived projects are hidden from list_projects (unless includeArchived is true) but can be restored with unarchive_project.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID to archive"
+          description: "Project ID to archive (format: prj_xxxxx)"
         }
       },
       required: ["projectId"]
@@ -25039,13 +25232,13 @@ var archiveProjectTool = {
 var unarchiveProjectTool = {
   tool: {
     name: "unarchive_project",
-    description: "Unarchive a previously archived project.",
+    description: "Restore a previously archived project. The project will reappear in list_projects results.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID to unarchive"
+          description: "Project ID to unarchive (format: prj_xxxxx)"
         }
       },
       required: ["projectId"]
@@ -25064,7 +25257,7 @@ var unarchiveProjectTool = {
 var getProjectSummariesTool = {
   tool: {
     name: "get_project_summaries",
-    description: "Get all projects with summary statistics (ticket counts, member count) in a single efficient call",
+    description: "Get all projects with summary statistics (ticket counts by status, member count) in a single efficient call. Lighter than calling get_project_stats for each project individually.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -25083,13 +25276,13 @@ var getProjectSummariesTool = {
 var getProjectStatsTool = {
   tool: {
     name: "get_project_stats",
-    description: "Get detailed project statistics: ticket counts by status, completion rates, and member activity",
+    description: "Get detailed project statistics: ticket counts by status, completion rates, and member activity. For cross-project overview, use get_project_summaries instead.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID (format: prj_xxxxx)"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         }
       },
       required: ["projectId"]
@@ -25108,13 +25301,13 @@ var getProjectStatsTool = {
 var getProjectMembersTool = {
   tool: {
     name: "get_project_members",
-    description: "List all members of a project with their roles. Useful for finding who can be assigned tickets.",
+    description: "List all members of a project with their roles. Returns user IDs needed for assigneeId in create_ticket. Use get_available_project_members to find org members not yet in the project.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID (format: prj_xxxxx)"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         }
       },
       required: ["projectId"]
@@ -25148,7 +25341,7 @@ var projectTools = [
 var listTicketsTool = {
   tool: {
     name: "list_tickets",
-    description: "List tickets in a project with optional filters for status, assignee, priority, location, and tags",
+    description: "List tickets in a project with optional filters. Returns full ticket data. For lightweight search (id, number, title only), use quick_search_tickets instead. Combine filters for targeted queries.",
     inputSchema: {
       type: "object",
       properties: {
@@ -25213,13 +25406,13 @@ var listTicketsTool = {
 var getTicketTool = {
   tool: {
     name: "get_ticket",
-    description: "Get detailed information about a specific ticket including status, assignee, tags, and description",
+    description: "Get full details of a ticket: title, description, status, assignee, priority, size, type, acceptance criteria, and metadata. Use before update_ticket to get the current version for optimistic locking.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
@@ -25242,7 +25435,7 @@ var getTicketTool = {
 var getTicketByKeyTool = {
   tool: {
     name: "get_ticket_by_key",
-    description: 'Get a ticket by its human-readable key (e.g., "PROJ-123"). This is how users typically refer to tickets.',
+    description: 'Look up a ticket by its human-readable key (e.g., "PROJ-123"). This is how users typically reference tickets in conversation. Org context must be set or pass orgSlug.',
     inputSchema: {
       type: "object",
       properties: {
@@ -25282,37 +25475,37 @@ var getTicketByKeyTool = {
 var createTicketTool = {
   tool: {
     name: "create_ticket",
-    description: "Create a new ticket in a project. Returns the created ticket with its generated key.",
+    description: "Create a new ticket in a project. For high-quality tickets, always include: description (structured markdown with ## headings), acceptanceCriteria (Given/When/Then JSON), and typeSlug. After creation, call set_ticket_tags to add tags. Call find_similar_tickets first to check for duplicates. Use list_statuses, list_priorities, list_sizes to get required IDs.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project to create ticket in"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         },
         title: {
           type: "string",
-          description: `Ticket title (${LIMITS.TITLE_MIN}-${LIMITS.TITLE_MAX} characters)`
+          description: `Ticket title (${LIMITS.TITLE_MIN}-${LIMITS.TITLE_MAX} chars). Be concise and action-oriented. Start with a verb for tasks (e.g., "Implement Google OAuth login flow").`
         },
         description: {
           type: "string",
-          description: "Ticket description (optional, supports markdown)"
+          description: `Ticket description in markdown (max ${LIMITS.DESCRIPTION_MAX} chars). Structure with ## headings: "## Requirements" (bullet points), "## Technical Notes" (implementation details, APIs, constraints). Use **bold** for key terms, \`code\` for identifiers, bullet lists for readability. Start with a user story: "As a [role], I want [goal], so that [benefit]."`
         },
         statusId: {
           type: "string",
-          description: "Initial status ID (use list_statuses to get available statuses)"
+          description: "Initial status ID (format: sts_xxxxx). Use list_statuses to get valid IDs. Typically use the first/leftmost status for new tickets."
         },
         assigneeId: {
           type: "string",
-          description: "Assign to user ID (optional, use get_project_members to find users)"
+          description: "User ID to assign (optional). Use get_project_members to find valid user IDs."
         },
         priorityId: {
           type: "string",
-          description: "Priority entity ID (use list_priorities to get available priorities)"
+          description: "Priority ID (required, format: pri_xxxxx). Use list_priorities to get valid IDs for this project."
         },
         sizeId: {
           type: "string",
-          description: "Size entity ID (use list_sizes to get available sizes)"
+          description: "Size/effort ID (required, format: siz_xxxxx). Use list_sizes to get valid IDs for this project."
         },
         priority: {
           type: "string",
@@ -25327,28 +25520,28 @@ var createTicketTool = {
         location: {
           type: "string",
           enum: ["board", "backlog"],
-          description: "Where to create: board (active) or backlog (later)",
+          description: 'Where to create: "board" (active, visible on board columns) or "backlog" (for later). Default: board.',
           default: "board"
         },
         dueDate: {
           type: "string",
-          description: "Due date in ISO format (optional)"
+          description: 'Due date in ISO 8601 format (e.g., "2025-03-15T00:00:00.000Z"). Optional.'
         },
         releaseId: {
           type: "string",
-          description: "Assign to release ID (optional)"
+          description: "Assign to a release at creation (format: rel_xxxxx). Use list_releases or get_release_dropdown to find IDs. Optional."
         },
         typeSlug: {
           type: "string",
-          description: "Ticket type slug: bug, feature, task, etc. (optional, uses project default)"
+          description: 'Ticket type slug: "bug", "feature", "task", etc. Use list_ticket_types to see available types. Always set this for proper categorization.'
         },
         acceptanceCriteria: {
           type: "string",
-          description: "Acceptance criteria as JSON array: [{id, text, isChecked}] (optional)"
+          description: `Acceptance criteria as JSON string of array (max ${LIMITS.ACCEPTANCE_CRITERIA_MAX} chars). Format: [{"id":"ac-1","text":"Given a user on X page, When they do Y, Then Z happens","isChecked":false}]. Use Given/When/Then format. Include 3-8 criteria. Use unique IDs (ac-1, ac-2). Set isChecked to false for new tickets.`
         },
         parentId: {
           type: "string",
-          description: "Parent ticket ID for creating subtasks (optional)"
+          description: "Parent ticket ID for creating subtasks (format: tkt_xxxxx). The parent must be in the same project. Optional."
         }
       },
       required: ["projectId", "title", "statusId", "priorityId", "sizeId"]
@@ -25382,37 +25575,37 @@ var createTicketTool = {
 var updateTicketTool = {
   tool: {
     name: "update_ticket",
-    description: "Update ticket fields. Only provided fields are updated.",
+    description: "Update one or more ticket fields. Only provided fields are changed; omitted fields stay untouched. To clear a nullable field, pass null explicitly. For status changes, use move_ticket instead. Consider updating tags with set_ticket_tags if needed.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)."
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID to update"
+          description: "Ticket ID to update (format: tkt_xxxxx)."
         },
         title: {
           type: "string",
-          description: "New title"
+          description: `New title (${LIMITS.TITLE_MIN}-${LIMITS.TITLE_MAX} chars). Concise and action-oriented.`
         },
         description: {
           type: "string",
-          description: "New description (supports markdown)"
+          description: `New description in markdown (max ${LIMITS.DESCRIPTION_MAX} chars). Structure with ## headings: Requirements, Technical Notes. Use **bold**, \`code\`, bullet lists.`
         },
         assigneeId: {
           type: ["string", "null"],
-          description: "User ID to assign, or null to unassign"
+          description: "User ID to assign, or null to unassign. Use get_project_members to find IDs."
         },
         priorityId: {
           type: ["string", "null"],
-          description: "Priority entity ID (use list_priorities), or null to clear"
+          description: "Priority ID (use list_priorities), or null to clear."
         },
         sizeId: {
           type: ["string", "null"],
-          description: "Size entity ID (use list_sizes), or null to clear"
+          description: "Size ID (use list_sizes), or null to clear."
         },
         priority: {
           type: "string",
@@ -25426,27 +25619,27 @@ var updateTicketTool = {
         },
         dueDate: {
           type: ["string", "null"],
-          description: "New due date (ISO format), or null to clear"
+          description: 'Due date in ISO 8601 format (e.g., "2025-03-15T00:00:00.000Z"), or null to clear.'
         },
         releaseId: {
           type: ["string", "null"],
-          description: "Release ID, or null to remove from release"
+          description: "Release ID (format: rel_xxxxx), or null to remove from release."
         },
         typeSlug: {
           type: ["string", "null"],
-          description: "Ticket type slug, or null to remove type"
+          description: 'Ticket type slug ("bug", "feature", "task", etc.), or null to remove type. Use list_ticket_types for valid values.'
         },
         acceptanceCriteria: {
           type: ["string", "null"],
-          description: "Acceptance criteria as JSON array: [{id, text, isChecked}], or null to clear"
+          description: `Acceptance criteria as JSON string of array (max ${LIMITS.ACCEPTANCE_CRITERIA_MAX} chars): [{"id":"ac-1","text":"Given... When... Then...","isChecked":false}], or null to clear. Preserve existing criteria IDs when updating.`
         },
         parentId: {
           type: ["string", "null"],
-          description: "Parent ticket ID, or null to remove from parent"
+          description: "Parent ticket ID (format: tkt_xxxxx), or null to remove from parent."
         },
         version: {
           type: "number",
-          description: "Optimistic locking version (pass current version to prevent stale updates)"
+          description: "Optimistic locking version. Pass the ticket's current version to prevent overwriting concurrent edits. Get from get_ticket response."
         }
       },
       required: ["projectId", "ticketId"]
@@ -25492,13 +25685,13 @@ var updateTicketTool = {
 var moveTicketTool = {
   tool: {
     name: "move_ticket",
-    description: "Move a ticket to a different status column on the board, optionally specifying position",
+    description: "Move a ticket to a different status column. Call get_available_transitions first to check valid targets — moves to disallowed statuses will fail. For completing, use complete_ticket; for canceling, use abandon_ticket.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
@@ -25530,13 +25723,13 @@ var moveTicketTool = {
 var completeTicketTool = {
   tool: {
     name: "complete_ticket",
-    description: "Mark a ticket as complete. Moves it to the completed area.",
+    description: "Mark a ticket as done. Moves it to the Completed area (off the board). To undo, use reopen_ticket.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
@@ -25559,13 +25752,13 @@ var completeTicketTool = {
 var abandonTicketTool = {
   tool: {
     name: "abandon_ticket",
-    description: "Abandon a ticket (won't do). Optionally provide a reason.",
+    description: "Cancel a ticket (won't do). Moves it to the Abandoned area. Optionally provide a reason for the audit trail. To undo, use revive_ticket.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
@@ -25592,13 +25785,13 @@ var abandonTicketTool = {
 var reopenTicketTool = {
   tool: {
     name: "reopen_ticket",
-    description: "Reopen a completed ticket - moves it back to board or backlog",
+    description: 'Reopen a completed ticket, returning it to the board or backlog. If destination is "board", you must provide a statusId. Use list_statuses to get valid IDs.',
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
@@ -25631,13 +25824,13 @@ var reopenTicketTool = {
 var reviveTicketTool = {
   tool: {
     name: "revive_ticket",
-    description: "Revive an abandoned ticket - bring it back to board or backlog",
+    description: 'Bring back an abandoned ticket, returning it to the board or backlog. If destination is "board", you must provide a statusId.',
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
@@ -25670,13 +25863,13 @@ var reviveTicketTool = {
 var deleteTicketTool = {
   tool: {
     name: "delete_ticket",
-    description: "Soft delete a ticket (moves to trash, can be restored)",
+    description: `Soft-delete a ticket (moves to trash). Can be restored with restore_ticket. Prefer abandon_ticket for "won't do" tickets — delete is for accidental or junk tickets.`,
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
@@ -25699,13 +25892,13 @@ var deleteTicketTool = {
 var restoreTicketTool = {
   tool: {
     name: "restore_ticket",
-    description: "Restore a deleted ticket from trash",
+    description: "Restore a soft-deleted ticket from trash back to its previous location.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
@@ -25728,13 +25921,13 @@ var restoreTicketTool = {
 var moveToBacklogTool = {
   tool: {
     name: "move_to_backlog",
-    description: "Move a ticket from the board to the backlog for later",
+    description: "Move a ticket from the active board to the backlog (for later). The ticket retains its metadata but is no longer visible on board columns.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
@@ -25757,13 +25950,13 @@ var moveToBacklogTool = {
 var moveToBoardTool = {
   tool: {
     name: "move_to_board",
-    description: "Move a ticket from the backlog to the active board",
+    description: "Move a ticket from the backlog to the active board. Requires a statusId to place it in a specific column. Use list_statuses to get valid IDs.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
@@ -25790,13 +25983,13 @@ var moveToBoardTool = {
 var getCompletedTicketsTool = {
   tool: {
     name: "get_completed_tickets",
-    description: "Get list of completed tickets in a project",
+    description: "Get completed tickets in a project. Use for reviewing finished work or finding tickets to reopen.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         limit: {
           type: "number",
@@ -25820,13 +26013,13 @@ var getCompletedTicketsTool = {
 var getAbandonedTicketsTool = {
   tool: {
     name: "get_abandoned_tickets",
-    description: "Get list of abandoned tickets in a project",
+    description: "Get abandoned (canceled) tickets in a project. Use for reviewing discarded work or finding tickets to revive.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         limit: {
           type: "number",
@@ -25850,13 +26043,13 @@ var getAbandonedTicketsTool = {
 var getTrashedTicketsTool = {
   tool: {
     name: "get_trashed_tickets",
-    description: "Get list of trashed (soft-deleted) tickets in a project",
+    description: "Get trashed (soft-deleted) tickets in a project. Trashed tickets can be restored with restore_ticket.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         limit: {
           type: "number",
@@ -25880,7 +26073,7 @@ var getTrashedTicketsTool = {
 var getMyTicketsTool = {
   tool: {
     name: "get_my_tickets",
-    description: "Get all tickets assigned to the current user. Can filter by project, location, and priority.",
+    description: 'Get all tickets assigned to the current user. Works across all projects unless filtered. Useful for "what am I working on?" and daily standup prep.',
     inputSchema: {
       type: "object",
       properties: {
@@ -25927,7 +26120,7 @@ var getMyTicketsTool = {
 var getOverdueTicketsTool = {
   tool: {
     name: "get_overdue_tickets",
-    description: "Get all tickets that are past their due date. Helps identify delayed work that needs attention.",
+    description: "Get tickets past their due date. Pair with get_tickets_due_soon for a complete deadline picture. Useful for standup reviews and priority triage.",
     inputSchema: {
       type: "object",
       properties: {
@@ -25970,7 +26163,7 @@ var getOverdueTicketsTool = {
 var getTicketsDueSoonTool = {
   tool: {
     name: "get_tickets_due_soon",
-    description: "Get tickets due within a specified number of days. Helps with proactive deadline management.",
+    description: "Get tickets due within N days (default: 7). Returns only upcoming deadlines, not overdue. Pair with get_overdue_tickets for complete deadline awareness.",
     inputSchema: {
       type: "object",
       properties: {
@@ -26022,13 +26215,13 @@ var getTicketsDueSoonTool = {
 var getTicketCountsTool = {
   tool: {
     name: "get_ticket_counts",
-    description: "Get ticket counts by location (board, backlog, completed, abandoned, trash). Quick overview without fetching ticket data.",
+    description: "Get ticket counts by location (board, backlog, completed, abandoned, trash). Lightweight overview without fetching ticket data. Use for dashboards and project health checks.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         }
       },
       required: ["projectId"]
@@ -26047,13 +26240,13 @@ var getTicketCountsTool = {
 var quickSearchTicketsTool = {
   tool: {
     name: "quick_search_tickets",
-    description: "Lightweight ticket search returning only id, number, title, and status. Faster than list_tickets for finding tickets by name.",
+    description: "Fast ticket search returning minimal data (id, number, title, status only). Use to find a ticket by name before calling get_ticket for full details. Lighter and faster than list_tickets.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         search: {
           type: "string",
@@ -26081,13 +26274,13 @@ var quickSearchTicketsTool = {
 var getTicketChildrenTool = {
   tool: {
     name: "get_ticket_children",
-    description: "Get subtasks (child tickets) of a ticket",
+    description: "Get all subtasks of a parent ticket. Create subtasks using create_ticket with the parentId parameter.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
@@ -26110,13 +26303,13 @@ var getTicketChildrenTool = {
 var listBacklogTicketsTool = {
   tool: {
     name: "list_backlog_tickets",
-    description: "List tickets in the backlog with cursor-based pagination. Use for browsing backlog items.",
+    description: "Browse backlog tickets with cursor-based pagination. Use for sprint planning — review backlog items before assigning to a release with assign_tickets_to_release.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         cursor: {
           type: "string",
@@ -26179,13 +26372,13 @@ var ticketTools = [
 var listStatusesTool = {
   tool: {
     name: "list_statuses",
-    description: "List all workflow statuses (columns) for a project. Use this to find valid status IDs for creating or moving tickets.",
+    description: "List all workflow statuses (board columns) for a project. Returns status IDs needed for create_ticket, move_ticket, and move_to_board. Call once per session and cache the IDs.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         }
       },
       required: ["projectId"]
@@ -26204,13 +26397,13 @@ var listStatusesTool = {
 var createStatusTool = {
   tool: {
     name: "create_status",
-    description: "Create a new workflow status (board column). Requires settings access.",
+    description: "Create a new workflow status (board column). New status appears as the rightmost column. Requires project manager or admin role.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         name: {
           type: "string",
@@ -26237,17 +26430,17 @@ var createStatusTool = {
 var updateStatusTool = {
   tool: {
     name: "update_status",
-    description: "Update a workflow status name or color. Requires settings access.",
+    description: "Update a workflow status name or color. Requires project manager or admin role.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         statusId: {
           type: "string",
-          description: "Status ID to update"
+          description: "Status ID to update (format: sts_xxxxx). Use list_statuses to find IDs."
         },
         name: {
           type: "string",
@@ -26279,17 +26472,17 @@ var updateStatusTool = {
 var deleteStatusTool = {
   tool: {
     name: "delete_status",
-    description: "Delete a workflow status. Tickets in this status must be moved first. Requires settings access.",
+    description: "Delete a workflow status. Tickets in this status must be moved first with batch_move_tickets. Requires project manager or admin role.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         statusId: {
           type: "string",
-          description: "Status ID to delete"
+          description: "Status ID to delete (format: sts_xxxxx)"
         }
       },
       required: ["projectId", "statusId"]
@@ -26308,13 +26501,13 @@ var deleteStatusTool = {
 var getAvailableTransitionsTool = {
   tool: {
     name: "get_available_transitions",
-    description: "Get which statuses a ticket can move to from a given status. Useful before moving a ticket.",
+    description: "Get valid target statuses for a move from a given status. ALWAYS call this before move_ticket — invalid moves will fail. If no transitions are defined, all moves are allowed.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         statusId: {
           type: "string",
@@ -26337,13 +26530,13 @@ var getAvailableTransitionsTool = {
 var listTransitionsTool = {
   tool: {
     name: "list_transitions",
-    description: "List all workflow transitions (rules for which status can move to which). Shows the full transition graph.",
+    description: "List the full workflow transition graph: which status can move to which. Use for understanding workflow rules. For checking a specific ticket's options, use get_available_transitions instead.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         }
       },
       required: ["projectId"]
@@ -26362,13 +26555,13 @@ var listTransitionsTool = {
 var createTransitionTool = {
   tool: {
     name: "create_transition",
-    description: "Create a workflow transition rule allowing tickets to move from one status to another. Requires settings access.",
+    description: "Create a workflow transition rule allowing tickets to move from one status to another. Use list_statuses to get status IDs. Requires project manager or admin role.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         fromStatusId: {
           type: "string",
@@ -26395,13 +26588,13 @@ var createTransitionTool = {
 var deleteTransitionTool = {
   tool: {
     name: "delete_transition",
-    description: "Delete a workflow transition rule. Requires settings access.",
+    description: "Delete a workflow transition rule, allowing free movement between these statuses. Requires project manager or admin role.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         fromStatusId: {
           type: "string",
@@ -26440,17 +26633,17 @@ var workflowTools = [
 var listCommentsTool = {
   tool: {
     name: "list_comments",
-    description: "List all comments on a ticket",
+    description: "List all comments on a ticket, ordered chronologically. Use to review discussion history before adding a new comment.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         },
         limit: {
           type: "number",
@@ -26474,21 +26667,21 @@ var listCommentsTool = {
 var addCommentTool = {
   tool: {
     name: "add_comment",
-    description: "Add a comment to a ticket",
+    description: "Add a comment to a ticket. Supports markdown formatting. Use for status updates, questions, or discussion.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         },
         content: {
           type: "string",
-          description: `Comment text (supports markdown, max ${LIMITS.COMMENT_MAX} characters)`
+          description: `Comment text in markdown (max ${LIMITS.COMMENT_MAX} chars). Supports **bold**, *italic*, \`code\`, code blocks, [links](url), and bullet lists.`
         }
       },
       required: ["projectId", "ticketId", "content"]
@@ -26507,21 +26700,21 @@ var addCommentTool = {
 var updateCommentTool = {
   tool: {
     name: "update_comment",
-    description: "Edit an existing comment (only the comment author can edit)",
+    description: "Edit an existing comment. Only the original author can edit. Previous versions are preserved in comment history (see get_comment_history).",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         },
         commentId: {
           type: "string",
-          description: "Comment ID to edit"
+          description: "Comment ID to edit (from list_comments response)"
         },
         content: {
           type: "string",
@@ -26544,21 +26737,21 @@ var updateCommentTool = {
 var deleteCommentTool = {
   tool: {
     name: "delete_comment",
-    description: "Delete a comment (only the comment author can delete)",
+    description: "Delete a comment permanently. Only the original author can delete. This cannot be undone.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         },
         commentId: {
           type: "string",
-          description: "Comment ID to delete"
+          description: "Comment ID to delete (from list_comments response)"
         }
       },
       required: ["projectId", "ticketId", "commentId"]
@@ -26577,21 +26770,21 @@ var deleteCommentTool = {
 var getCommentHistoryTool = {
   tool: {
     name: "get_comment_history",
-    description: "Get the edit history of a comment (previous versions)",
+    description: "Get the edit history of a comment showing all previous versions. Use to see what was changed and when.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         },
         commentId: {
           type: "string",
-          description: "Comment ID"
+          description: "Comment ID (from list_comments response)"
         }
       },
       required: ["projectId", "ticketId", "commentId"]
@@ -26619,13 +26812,13 @@ var commentTools = [
 var listTagsTool = {
   tool: {
     name: "list_tags",
-    description: "List all tags available in a project",
+    description: "List all tags in a project. Call this before create_ticket to find existing tag IDs for set_ticket_tags. If a needed tag does not exist, create it with create_tag first.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         }
       },
       required: ["projectId"]
@@ -26644,17 +26837,17 @@ var listTagsTool = {
 var createTagTool = {
   tool: {
     name: "create_tag",
-    description: "Create a new tag in a project",
+    description: 'Create a new tag in a project. Use lowercase-kebab-case names (e.g., "google-oauth", "api", "frontend"). Check list_tags first to avoid duplicates. After creating, use set_ticket_tags or add_tag_to_ticket to apply it.',
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         name: {
           type: "string",
-          description: "Tag name (max 30 characters)"
+          description: `Tag name (max ${LIMITS.TAG_NAME_MAX} chars). Use lowercase-kebab-case (e.g., "google-oauth", "user-login").`
         },
         color: {
           type: "string",
@@ -26679,17 +26872,17 @@ var createTagTool = {
 var updateTagTool = {
   tool: {
     name: "update_tag",
-    description: "Update a tag name or color",
+    description: "Update a tag name or color. Changes apply to all tickets using this tag.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         tagId: {
           type: "string",
-          description: "Tag ID to update"
+          description: "Tag ID to update (format: tag_xxxxx). Use list_tags to find IDs."
         },
         name: {
           type: "string",
@@ -26722,17 +26915,17 @@ var updateTagTool = {
 var deleteTagTool = {
   tool: {
     name: "delete_tag",
-    description: "Delete a tag from the project. Removes it from all tickets.",
+    description: "Permanently delete a tag from the project. Removes it from ALL tickets. There is no undo — use with caution.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         tagId: {
           type: "string",
-          description: "Tag ID to delete"
+          description: "Tag ID to delete (format: tag_xxxxx)"
         }
       },
       required: ["projectId", "tagId"]
@@ -26751,17 +26944,17 @@ var deleteTagTool = {
 var getTicketTagsTool = {
   tool: {
     name: "get_ticket_tags",
-    description: "Get all tags on a specific ticket",
+    description: "Get all tags currently on a ticket. Use before set_ticket_tags if you need to preserve existing tags while adding new ones.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         }
       },
       required: ["projectId", "ticketId"]
@@ -26780,17 +26973,17 @@ var getTicketTagsTool = {
 var setTicketTagsTool = {
   tool: {
     name: "set_ticket_tags",
-    description: "Replace all tags on a ticket with a new set. Pass an empty array to remove all tags.",
+    description: "Replace ALL tags on a ticket with a new set. This overwrites existing tags — pass the complete list of desired tag IDs. Pass empty array to remove all tags. Prefer this over multiple add_tag_to_ticket calls when setting multiple tags at once.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         },
         tagIds: {
           type: "array",
@@ -26814,17 +27007,17 @@ var setTicketTagsTool = {
 var addTagToTicketTool = {
   tool: {
     name: "add_tag_to_ticket",
-    description: "Add a tag to a ticket",
+    description: "Add a single tag to a ticket without affecting existing tags. Use set_ticket_tags instead when applying multiple tags at once (fewer API calls).",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         },
         tagId: {
           type: "string",
@@ -26847,21 +27040,21 @@ var addTagToTicketTool = {
 var removeTagFromTicketTool = {
   tool: {
     name: "remove_tag_from_ticket",
-    description: "Remove a tag from a ticket",
+    description: "Remove a single tag from a ticket. Other tags remain unchanged.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         },
         tagId: {
           type: "string",
-          description: "Tag ID to remove"
+          description: "Tag ID to remove (format: tag_xxxxx). Use get_ticket_tags to see current tags."
         }
       },
       required: ["projectId", "ticketId", "tagId"]
@@ -26892,13 +27085,13 @@ var tagTools = [
 var listTicketTypesTool = {
   tool: {
     name: "list_ticket_types",
-    description: "List all ticket types available in a project (e.g., Bug, Feature, Task). Use this to find valid typeSlug values when creating tickets.",
+    description: "List ticket types for a project (e.g., Bug, Feature, Task). Returns slug values needed for the typeSlug parameter in create_ticket. Call once per session and cache.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         }
       },
       required: ["projectId"]
@@ -26917,13 +27110,13 @@ var listTicketTypesTool = {
 var getTicketTypeTool = {
   tool: {
     name: "get_ticket_type",
-    description: "Get details of a specific ticket type by slug",
+    description: 'Get details of a specific ticket type by its slug (e.g., "bug", "feature").',
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         slug: {
           type: "string",
@@ -26952,7 +27145,7 @@ var createTicketTypeTool = {
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         name: {
           type: "string",
@@ -26993,7 +27186,7 @@ var updateTicketTypeTool = {
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         slug: {
           type: "string",
@@ -27035,7 +27228,7 @@ var deleteTicketTypeTool = {
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         slug: {
           type: "string",
@@ -27071,13 +27264,13 @@ var ticketTypeTools = [
 var listPrioritiesTool = {
   tool: {
     name: "list_priorities",
-    description: "List all priorities defined in a project. Projects can have custom priority levels.",
+    description: "List priority levels for a project. Returns IDs needed for the priorityId parameter in create_ticket and update_ticket. Call once per session and cache.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         }
       },
       required: ["projectId"]
@@ -27096,17 +27289,17 @@ var listPrioritiesTool = {
 var getPriorityTool = {
   tool: {
     name: "get_priority",
-    description: "Get details of a specific priority by ID",
+    description: "Get details of a specific priority level by ID (format: pri_xxxxx).",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         priorityId: {
           type: "string",
-          description: "Priority ID"
+          description: "Priority ID (format: pri_xxxxx)"
         }
       },
       required: ["projectId", "priorityId"]
@@ -27131,7 +27324,7 @@ var createPriorityTool = {
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         name: {
           type: "string",
@@ -27172,11 +27365,11 @@ var updatePriorityTool = {
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         priorityId: {
           type: "string",
-          description: "Priority ID to update"
+          description: "Priority ID to update (format: pri_xxxxx)"
         },
         name: {
           type: "string",
@@ -27220,11 +27413,11 @@ var deletePriorityTool = {
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         priorityId: {
           type: "string",
-          description: "Priority ID to delete"
+          description: "Priority ID to delete (format: pri_xxxxx)"
         },
         replaceWithId: {
           type: "string",
@@ -27256,13 +27449,13 @@ var priorityTools = [
 var listSizesTool = {
   tool: {
     name: "list_sizes",
-    description: "List all sizes defined in a project. Projects can have custom size levels.",
+    description: "List size/effort levels for a project. Returns IDs needed for the sizeId parameter in create_ticket and update_ticket. Call once per session and cache.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         }
       },
       required: ["projectId"]
@@ -27281,17 +27474,17 @@ var listSizesTool = {
 var getSizeTool = {
   tool: {
     name: "get_size",
-    description: "Get details of a specific size by ID",
+    description: "Get details of a specific size level by ID (format: siz_xxxxx).",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         sizeId: {
           type: "string",
-          description: "Size ID"
+          description: "Size ID (format: siz_xxxxx)"
         }
       },
       required: ["projectId", "sizeId"]
@@ -27316,7 +27509,7 @@ var createSizeTool = {
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         name: {
           type: "string",
@@ -27357,11 +27550,11 @@ var updateSizeTool = {
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         sizeId: {
           type: "string",
-          description: "Size ID to update"
+          description: "Size ID to update (format: siz_xxxxx)"
         },
         name: {
           type: "string",
@@ -27405,11 +27598,11 @@ var deleteSizeTool = {
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         sizeId: {
           type: "string",
-          description: "Size ID to delete"
+          description: "Size ID to delete (format: siz_xxxxx)"
         },
         replaceWithId: {
           type: "string",
@@ -27441,13 +27634,13 @@ var sizeTools = [
 var listReleasesTool = {
   tool: {
     name: "list_releases",
-    description: "List releases in a project",
+    description: "List releases (sprints/milestones) in a project. Filter by status: open, released, or all.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         status: {
           type: "string",
@@ -27472,17 +27665,17 @@ var listReleasesTool = {
 var getReleaseTool = {
   tool: {
     name: "get_release",
-    description: "Get detailed information about a specific release",
+    description: "Get full release details including ticket counts, progress, and target date. Use before update_release to get the version for optimistic locking.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         }
       },
       required: ["projectId", "releaseId"]
@@ -27501,13 +27694,13 @@ var getReleaseTool = {
 var createReleaseTool = {
   tool: {
     name: "create_release",
-    description: "Create a new release for grouping tickets",
+    description: "Create a new release (sprint/milestone) for grouping tickets. After creating, use assign_tickets_to_release to add tickets. Track progress with get_release_burndown.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         name: {
           type: "string",
@@ -27542,21 +27735,21 @@ var createReleaseTool = {
 var assignTicketToReleaseTool = {
   tool: {
     name: "assign_ticket_to_release",
-    description: "Assign a ticket to a release, or remove from release by passing null",
+    description: "Assign a single ticket to a release, or remove from release by passing null. Use assign_tickets_to_release for bulk assignment.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         },
         releaseId: {
           type: ["string", "null"],
-          description: "Release ID, or null to remove from release"
+          description: "Release ID (format: rel_xxxxx), or null to remove from release. Use list_releases to find IDs."
         }
       },
       required: ["projectId", "ticketId", "releaseId"]
@@ -27575,17 +27768,17 @@ var assignTicketToReleaseTool = {
 var markReleaseShippedTool = {
   tool: {
     name: "mark_release_shipped",
-    description: "Mark a release as shipped/released",
+    description: "Mark a release as shipped. Verify all tickets are complete first with get_release_tickets. To undo, use reopen_release.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         }
       },
       required: ["projectId", "releaseId"]
@@ -27604,17 +27797,17 @@ var markReleaseShippedTool = {
 var getReleaseTicketsTool = {
   tool: {
     name: "get_release_tickets",
-    description: "Get all tickets assigned to a release",
+    description: "Get all tickets assigned to a release with their status. Use before mark_release_shipped to verify all tickets are complete.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         }
       },
       required: ["projectId", "releaseId"]
@@ -27633,17 +27826,17 @@ var getReleaseTicketsTool = {
 var updateReleaseTool = {
   tool: {
     name: "update_release",
-    description: "Update release details (name, description, target date)",
+    description: "Update release name, description, or target date. Requires the current version for optimistic locking (get from get_release).",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         },
         name: {
           type: "string",
@@ -27687,17 +27880,17 @@ var updateReleaseTool = {
 var deleteReleaseTool = {
   tool: {
     name: "delete_release",
-    description: "Delete a release (soft delete - can be restored)",
+    description: "Soft-delete a release. Tickets remain but lose their release assignment. Can be restored with restore_release.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         }
       },
       required: ["projectId", "releaseId"]
@@ -27722,11 +27915,11 @@ var reopenReleaseTool = {
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         }
       },
       required: ["projectId", "releaseId"]
@@ -27751,11 +27944,11 @@ var restoreReleaseTool = {
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         }
       },
       required: ["projectId", "releaseId"]
@@ -27774,17 +27967,17 @@ var restoreReleaseTool = {
 var getReleaseBurndownTool = {
   tool: {
     name: "get_release_burndown",
-    description: "Get burndown chart data for a release, showing progress over time",
+    description: "Get burndown data for a release: total tickets, completed count, and daily progress. Use for sprint reviews and progress tracking.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         }
       },
       required: ["projectId", "releaseId"]
@@ -27803,17 +27996,17 @@ var getReleaseBurndownTool = {
 var assignTicketsToReleaseTool = {
   tool: {
     name: "assign_tickets_to_release",
-    description: "Assign multiple tickets to a release at once (bulk operation)",
+    description: "Assign multiple tickets to a release in one call. The primary tool for sprint planning. Use list_backlog_tickets to find ticket IDs.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         },
         ticketIds: {
           type: "array",
@@ -27837,17 +28030,17 @@ var assignTicketsToReleaseTool = {
 var removeTicketsFromReleaseTool = {
   tool: {
     name: "remove_tickets_from_release",
-    description: "Remove multiple tickets from a release (bulk operation)",
+    description: "Remove multiple tickets from a release in one call. Tickets stay in the project but lose their release assignment.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         },
         ticketIds: {
           type: "array",
@@ -27871,13 +28064,13 @@ var removeTicketsFromReleaseTool = {
 var getReleaseDropdownTool = {
   tool: {
     name: "get_release_dropdown",
-    description: "Get a minimal list of releases (id and name only) for ticket assignment. Lighter than list_releases.",
+    description: "Get a lightweight list of releases (id and name only). Faster than list_releases. Use when you just need a release ID for ticket assignment.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         }
       },
       required: ["projectId"]
@@ -27896,13 +28089,13 @@ var getReleaseDropdownTool = {
 var quickSearchReleasesTool = {
   tool: {
     name: "quick_search_releases",
-    description: "Search releases by name or description",
+    description: "Search releases by name or description. Returns lightweight results for finding a specific release.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         search: {
           type: "string",
@@ -27930,17 +28123,17 @@ var quickSearchReleasesTool = {
 var getReleaseHistoryTool = {
   tool: {
     name: "get_release_history",
-    description: "Get the changelog/history of a release (status changes, ticket additions, etc.)",
+    description: "Get the audit trail for a release: status changes, ticket additions/removals, and edits.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         },
         limit: {
           type: "number",
@@ -27964,17 +28157,17 @@ var getReleaseHistoryTool = {
 var getReleaseActivitiesTool = {
   tool: {
     name: "get_release_activities",
-    description: "Get ticket activities within a release (completions, status changes, etc.)",
+    description: "Get ticket-level activity within a release: completions, status changes, and assignments. Use for sprint review summaries.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         releaseId: {
           type: "string",
-          description: "Release ID"
+          description: "Release ID (format: rel_xxxxx). Use list_releases to find IDs."
         },
         limit: {
           type: "number",
@@ -28019,21 +28212,21 @@ var releaseTools = [
 var getTicketHistoryTool = {
   tool: {
     name: "get_ticket_history",
-    description: "Get the change history for a ticket (status changes, assignments, updates, etc.)",
+    description: "Get the full change history for a ticket: status changes, field updates, assignments, and more. Ordered newest-first. Useful for auditing and understanding ticket lifecycle.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         },
         limit: {
           type: "number",
-          description: "Maximum history entries to return (default: 50)",
+          description: "Maximum history entries to return (default: 50, max: 200)",
           default: 50
         }
       },
@@ -28053,21 +28246,21 @@ var getTicketHistoryTool = {
 var getProjectActivityTool = {
   tool: {
     name: "get_project_activity",
-    description: "Get recent activity across a project (all ticket changes, comments, etc.)",
+    description: "Get recent activity across all tickets in a project: creates, updates, comments, status changes. Useful for standup reports and daily digests. Filter by date range.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         },
         from: {
           type: "string",
-          description: "Start date in ISO format (optional)"
+          description: 'Start date in ISO 8601 format (e.g., "2025-01-15T00:00:00Z"). Optional.'
         },
         to: {
           type: "string",
-          description: "End date in ISO format (optional)"
+          description: 'End date in ISO 8601 format (e.g., "2025-01-31T23:59:59Z"). Optional.'
         }
       },
       required: ["projectId"]
@@ -28092,13 +28285,13 @@ var historyTools = [
 var getMemberAnalyticsTool = {
   tool: {
     name: "get_member_analytics",
-    description: "Get per-member statistics: tickets assigned, completed, and activity for each project member.",
+    description: "Get per-member statistics: tickets assigned, completed, and activity for each project member. Useful for workload balancing and standup reports.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         }
       },
       required: ["projectId"]
@@ -28117,13 +28310,13 @@ var getMemberAnalyticsTool = {
 var getCycleTimeAnalyticsTool = {
   tool: {
     name: "get_cycle_time_analytics",
-    description: "Get cycle time analytics: how long tickets take to complete, broken down by status transitions.",
+    description: "Get cycle time analytics: average time tickets spend in each status and total time to completion. Useful for identifying workflow bottlenecks.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         }
       },
       required: ["projectId"]
@@ -28142,13 +28335,13 @@ var getCycleTimeAnalyticsTool = {
 var getDistributionAnalyticsTool = {
   tool: {
     name: "get_distribution_analytics",
-    description: "Get distribution charts: tickets by priority, type, tag, assignee, and size.",
+    description: "Get ticket distribution breakdowns: count by priority, type, tag, assignee, and size. Useful for understanding project composition and identifying imbalances.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         }
       },
       required: ["projectId"]
@@ -28174,13 +28367,13 @@ var analyticsTools = [
 var listNotificationsTool = {
   tool: {
     name: "list_notifications",
-    description: "List recent notifications for the current user",
+    description: "List recent notifications for the current user (ticket assignments, comments, status changes). Use get_unread_count to check if there are new notifications first.",
     inputSchema: {
       type: "object",
       properties: {
         limit: {
           type: "number",
-          description: "Maximum notifications to return (default: 20)",
+          description: "Maximum notifications to return (default: 20, max: 100)",
           default: 20
         }
       }
@@ -28199,7 +28392,7 @@ var listNotificationsTool = {
 var getUnreadCountTool = {
   tool: {
     name: "get_unread_count",
-    description: "Get the count of unread notifications",
+    description: "Get the total count of unread notifications. Use this for a quick check before fetching the full list with list_notifications.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -28218,13 +28411,13 @@ var getUnreadCountTool = {
 var markNotificationReadTool = {
   tool: {
     name: "mark_notification_read",
-    description: "Mark a specific notification as read",
+    description: "Mark a specific notification as read. Use mark_all_notifications_read to clear all at once.",
     inputSchema: {
       type: "object",
       properties: {
         notificationId: {
           type: "string",
-          description: "Notification ID"
+          description: "Notification ID (from list_notifications response)"
         }
       },
       required: ["notificationId"]
@@ -28243,7 +28436,7 @@ var markNotificationReadTool = {
 var markAllNotificationsReadTool = {
   tool: {
     name: "mark_all_notifications_read",
-    description: "Mark all notifications as read",
+    description: "Mark all notifications as read in one call. Use this to clear the notification badge.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -28262,7 +28455,7 @@ var markAllNotificationsReadTool = {
 var getUnreadCountsTool = {
   tool: {
     name: "get_unread_counts",
-    description: "Get unread notification counts with per-project breakdown",
+    description: "Get unread notification counts with per-project breakdown. More detailed than get_unread_count — shows which projects have pending notifications.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -28290,7 +28483,7 @@ var notificationTools = [
 var polishTitleTool = {
   tool: {
     name: "polish_title",
-    description: "Use AI to improve a ticket title - make it clearer and more actionable",
+    description: "AI-powered title improvement. Makes titles clearer and more actionable. Use before create_ticket when the user provides a vague title. Consumes AI token quota (check with get_ai_usage).",
     inputSchema: {
       type: "object",
       properties: {
@@ -28319,7 +28512,7 @@ var polishTitleTool = {
 var generateDescriptionTool = {
   tool: {
     name: "generate_description",
-    description: "Use AI to generate a detailed ticket description from a title",
+    description: "AI-generated structured ticket description from a title. Returns markdown with headings and bullet points. Use as a starting point, then refine with refine_description if needed. Consumes AI token quota.",
     inputSchema: {
       type: "object",
       properties: {
@@ -28352,7 +28545,7 @@ var generateDescriptionTool = {
 var findSimilarTicketsTool = {
   tool: {
     name: "find_similar_tickets",
-    description: "Find tickets similar to a given query using semantic search. Useful for finding duplicates or related work.",
+    description: "Semantic search for similar tickets. Use BEFORE creating a ticket to check for duplicates. Also useful for finding related work. Returns similarity scores.",
     inputSchema: {
       type: "object",
       properties: {
@@ -28386,7 +28579,7 @@ var findSimilarTicketsTool = {
 var fixGrammarTool = {
   tool: {
     name: "fix_grammar",
-    description: "Use AI to fix grammar and spelling in text",
+    description: "AI grammar and spelling correction. Use on ticket descriptions or comments before saving. Preserves markdown formatting. Max 5000 chars input. Consumes AI quota.",
     inputSchema: {
       type: "object",
       properties: {
@@ -28415,7 +28608,7 @@ var fixGrammarTool = {
 var improveClarityTool = {
   tool: {
     name: "improve_clarity",
-    description: "Use AI to make text clearer and more concise",
+    description: "AI rewrite for clarity and conciseness. Use on verbose or unclear descriptions. Preserves structure and markdown. Max 5000 chars input. Consumes AI quota.",
     inputSchema: {
       type: "object",
       properties: {
@@ -28444,7 +28637,7 @@ var improveClarityTool = {
 var checkClarityTool = {
   tool: {
     name: "check_clarity",
-    description: "Use AI to check if a ticket title needs clarification questions before generating a description",
+    description: "AI check whether a ticket title is clear enough to generate a good description. If unclear, returns clarifying questions to ask the user. Call this before generate_description when the title might be ambiguous.",
     inputSchema: {
       type: "object",
       properties: {
@@ -28473,7 +28666,7 @@ var checkClarityTool = {
 var refineDescriptionTool = {
   tool: {
     name: "refine_description",
-    description: "Use AI to refine an existing ticket description based on feedback",
+    description: 'AI refinement of an existing description based on feedback. Pass the current description and natural-language instructions (e.g., "add error handling details", "make it shorter"). Max 1000 chars feedback. Consumes AI quota.',
     inputSchema: {
       type: "object",
       properties: {
@@ -28506,7 +28699,7 @@ var refineDescriptionTool = {
 var suggestAttributesTool = {
   tool: {
     name: "suggest_attributes",
-    description: "Use AI to suggest ticket attributes (priority, size, type, tags) based on title and optional description",
+    description: "AI-suggested priority, size, type, and tags based on title and description. Returns IDs matching the project's configured values. Use after writing the description but before create_ticket to auto-fill attributes.",
     inputSchema: {
       type: "object",
       properties: {
@@ -28551,7 +28744,7 @@ var aiTools = [
 var getMCPUsageTool = {
   tool: {
     name: "get_mcp_usage",
-    description: "Check MCP usage status - how many requests used today and remaining quota",
+    description: "Check MCP API usage status: requests used today, daily quota, and remaining calls. Call this if you get rate-limit errors.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -28570,7 +28763,7 @@ var getMCPUsageTool = {
 var getAIUsageTool = {
   tool: {
     name: "get_ai_usage",
-    description: "Check AI usage status - tokens used this week and remaining quota",
+    description: "Check AI feature usage: tokens consumed this week, weekly quota, and remaining capacity. AI tools (check_clarity, generate_description, etc.) consume tokens from this quota.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -28595,7 +28788,7 @@ var usageTools = [
 var listOrganizationsTool = {
   tool: {
     name: "list_organizations",
-    description: "List all organizations the current user belongs to",
+    description: "List all organizations the current user belongs to. Call this first during setup, then use set_organization to pick the active org.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -28617,13 +28810,13 @@ var listOrganizationsTool = {
 var setOrganizationTool = {
   tool: {
     name: "set_organization",
-    description: "Set the active organization context for subsequent API calls. Use list_organizations to see available orgs.",
+    description: "Set the active organization context. All subsequent API calls (list_projects, create_ticket, etc.) operate within this org. Call list_organizations first to get available org IDs.",
     inputSchema: {
       type: "object",
       properties: {
         orgId: {
           type: "string",
-          description: "Organization ID to set as active"
+          description: "Organization ID to set as active (format: org_xxxxx). Use list_organizations to find IDs."
         }
       },
       required: ["orgId"]
@@ -28650,7 +28843,7 @@ var setOrganizationTool = {
 var getCurrentOrganizationTool = {
   tool: {
     name: "get_current_organization",
-    description: "Get the currently active organization context",
+    description: "Get the currently active organization. Returns the org set via set_organization, or the default org if none was set.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -28674,13 +28867,13 @@ var getCurrentOrganizationTool = {
 var listOrgMembersTool = {
   tool: {
     name: "list_organization_members",
-    description: "List all members in the current organization",
+    description: "List all members in the current organization. Returns user IDs needed for add_project_member and assigneeId in create_ticket.",
     inputSchema: {
       type: "object",
       properties: {
         search: {
           type: "string",
-          description: "Search by name or email (optional)"
+          description: "Filter by name or email substring (optional)"
         }
       }
     }
@@ -28698,13 +28891,13 @@ var listOrgMembersTool = {
 var getMemberProfileTool = {
   tool: {
     name: "get_member_profile",
-    description: "Get detailed profile of a specific team member",
+    description: "Get detailed profile of a specific team member including name, email, and avatar.",
     inputSchema: {
       type: "object",
       properties: {
         userId: {
           type: "string",
-          description: "User ID to look up"
+          description: "User ID (format: usr_xxxxx). Use list_organization_members to find IDs."
         }
       },
       required: ["userId"]
@@ -28723,7 +28916,7 @@ var getMemberProfileTool = {
 var getMyProfileTool = {
   tool: {
     name: "get_my_profile",
-    description: "Get the current user's profile information",
+    description: "Get the current authenticated user's profile: name, email, username, and avatar. Useful to get your own user ID for filtering (e.g., get_my_tickets).",
     inputSchema: {
       type: "object",
       properties: {}
@@ -28759,17 +28952,17 @@ var organizationTools = [
 var getWatchStatusTool = {
   tool: {
     name: "get_watch_status",
-    description: "Check if you are watching a ticket",
+    description: "Check if the current user is watching a ticket. Watched tickets send notifications on status changes, comments, and assignments.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         }
       },
       required: ["projectId", "ticketId"]
@@ -28788,17 +28981,17 @@ var getWatchStatusTool = {
 var toggleWatchTool = {
   tool: {
     name: "toggle_watch",
-    description: "Toggle watching a ticket. If watching, stops watching. If not watching, starts watching.",
+    description: "Toggle watching a ticket. If currently watching, stops watching (no more notifications). If not watching, starts watching. Use get_watch_status to check current state.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         }
       },
       required: ["projectId", "ticketId"]
@@ -28842,22 +29035,22 @@ async function mapWithConcurrency(items, fn, concurrency = BATCH_CONCURRENCY_LIM
 var batchMoveTicketsTool = {
   tool: {
     name: "batch_move_tickets",
-    description: `Move multiple tickets to a new status at once. Maximum ${LIMITS.BATCH_SIZE_MAX} tickets per batch.`,
+    description: `Move multiple tickets to a new status in one call. Use list_statuses to get valid status IDs. Maximum ${LIMITS.BATCH_SIZE_MAX} tickets per batch. Skips tickets where the transition is invalid.`,
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         },
         ticketIds: {
           type: "array",
           items: { type: "string" },
-          description: `Array of ticket IDs to move (max ${LIMITS.BATCH_SIZE_MAX})`
+          description: `Array of ticket IDs to move (format: tkt_xxxxx each, max ${LIMITS.BATCH_SIZE_MAX})`
         },
         toStatusId: {
           type: "string",
-          description: "Target status ID"
+          description: "Target status ID (format: sts_xxxxx). Use list_statuses to get valid IDs."
         }
       },
       required: ["projectId", "ticketIds", "toStatusId"]
@@ -28880,18 +29073,18 @@ var batchMoveTicketsTool = {
 var batchCompleteTicketsTool = {
   tool: {
     name: "batch_complete_tickets",
-    description: `Complete multiple tickets at once. Maximum ${LIMITS.BATCH_SIZE_MAX} tickets per batch.`,
+    description: `Mark multiple tickets as completed in one call. Equivalent to calling complete_ticket for each. Maximum ${LIMITS.BATCH_SIZE_MAX} tickets per batch. Returns per-ticket success/failure results.`,
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         },
         ticketIds: {
           type: "array",
           items: { type: "string" },
-          description: `Array of ticket IDs to complete (max ${LIMITS.BATCH_SIZE_MAX})`
+          description: `Array of ticket IDs to complete (format: tkt_xxxxx each, max ${LIMITS.BATCH_SIZE_MAX})`
         }
       },
       required: ["projectId", "ticketIds"]
@@ -28928,22 +29121,22 @@ var batchCompleteTicketsTool = {
 var batchAssignTicketsTool = {
   tool: {
     name: "batch_assign_tickets",
-    description: `Assign multiple tickets to a user at once. Maximum ${LIMITS.BATCH_SIZE_MAX} tickets per batch.`,
+    description: `Assign multiple tickets to a single user in one call, or pass null to unassign all. Use get_project_members to find valid user IDs. Maximum ${LIMITS.BATCH_SIZE_MAX} tickets per batch.`,
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         },
         ticketIds: {
           type: "array",
           items: { type: "string" },
-          description: `Array of ticket IDs to assign (max ${LIMITS.BATCH_SIZE_MAX})`
+          description: `Array of ticket IDs to assign (format: tkt_xxxxx each, max ${LIMITS.BATCH_SIZE_MAX})`
         },
         assigneeId: {
           type: ["string", "null"],
-          description: "User ID to assign to, or null to unassign all"
+          description: "User ID to assign to (format: usr_xxxxx), or null to unassign all. Use get_project_members to find user IDs."
         }
       },
       required: ["projectId", "ticketIds", "assigneeId"]
@@ -28983,17 +29176,17 @@ var batchTools = [
 var listAttachmentsTool = {
   tool: {
     name: "list_attachments",
-    description: "List all attachments on a ticket (read-only)",
+    description: "List all file attachments on a ticket (read-only). Returns file names, sizes, and URLs. Attachments are uploaded via the web UI — this tool only reads them.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         ticketId: {
           type: "string",
-          description: "Ticket ID"
+          description: "Ticket ID (format: tkt_xxxxx)"
         }
       },
       required: ["projectId", "ticketId"]
@@ -29017,13 +29210,13 @@ var attachmentTools = [
 var getAvailableProjectMembersTool = {
   tool: {
     name: "get_available_project_members",
-    description: "Get organization members who are NOT yet members of a project. Use this to find users to add to a project.",
+    description: "Get organization members who are NOT yet members of a project. Call this before add_project_member to find users you can add.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         }
       },
       required: ["projectId"]
@@ -29042,22 +29235,22 @@ var getAvailableProjectMembersTool = {
 var addProjectMemberTool = {
   tool: {
     name: "add_project_member",
-    description: "Add an organization member to a project. The user must already be an org member.",
+    description: "Add an organization member to a project. The user must already be an org member — use get_available_project_members to find eligible users.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx). Use list_projects to find IDs."
         },
         userId: {
           type: "string",
-          description: "User ID to add (use get_available_project_members to find available users)"
+          description: "User ID to add (format: usr_xxxxx). Use get_available_project_members to find eligible users."
         },
         role: {
           type: "string",
           enum: ["member", "admin"],
-          description: "Role in the project (default: member)",
+          description: 'Role in the project: "member" (default) or "admin" (can manage project settings)',
           default: "member"
         }
       },
@@ -29077,22 +29270,22 @@ var addProjectMemberTool = {
 var updateProjectMemberRoleTool = {
   tool: {
     name: "update_project_member_role",
-    description: "Update a member's role in a project (e.g., promote to admin or demote to member)",
+    description: "Update a project member's role (promote to admin or demote to member). Requires project admin role.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         userId: {
           type: "string",
-          description: "User ID to update"
+          description: "User ID to update (format: usr_xxxxx). Use get_project_members to find current members."
         },
         role: {
           type: "string",
           enum: ["member", "admin"],
-          description: "New role"
+          description: 'New role: "member" or "admin"'
         }
       },
       required: ["projectId", "userId", "role"]
@@ -29111,17 +29304,17 @@ var updateProjectMemberRoleTool = {
 var removeProjectMemberTool = {
   tool: {
     name: "remove_project_member",
-    description: "Remove a member from a project. They will lose access to the project but remain in the organization.",
+    description: "Remove a member from a project. They lose project access but remain in the organization. Requires project admin role.",
     inputSchema: {
       type: "object",
       properties: {
         projectId: {
           type: "string",
-          description: "Project ID"
+          description: "Project ID (format: prj_xxxxx)"
         },
         userId: {
           type: "string",
-          description: "User ID to remove"
+          description: "User ID to remove (format: usr_xxxxx). Use get_project_members to find current members."
         }
       },
       required: ["projectId", "userId"]
@@ -29148,13 +29341,41 @@ var projectMemberTools = [
 var TOOL_INDEX = {
   getting_started: {
     description: "Start here. Set your organization context before using other tools.",
+    setup: 'Run "npx @kanbodev/mcp login" to authenticate and auto-register the MCP server with your editor. Use "npx @kanbodev/mcp install" to re-register with newly installed editors.',
     steps: [
       "1. list_organizations — find your orgs",
       "2. set_organization — set active org (required before most tools)",
       "3. list_projects — discover projects",
-      "4. list_statuses — see workflow columns for a project"
+      "4. Cache IDs: list_statuses + list_priorities + list_sizes + list_ticket_types + list_tags"
     ]
   },
+  content_quality_guidelines: {
+    description: "Follow these guidelines when creating or updating tickets for professional-quality output.",
+    ticket_title: 'Concise, action-oriented. Start with a verb for tasks/bugs. 1-200 chars. Example: "Implement Google OAuth login flow"',
+    ticket_description: [
+      "Use markdown. Max 5000 chars. Structure with ## headings:",
+      "",
+      "As a [role], I want [goal], so that [benefit].",
+      "",
+      "## Requirements",
+      "- Bullet points of what needs to happen",
+      "",
+      "## Technical Notes",
+      "- Implementation hints, APIs, constraints, `code` references",
+      "",
+      "Use **bold** for key terms, `code` for identifiers, and bullet lists for readability."
+    ].join(`
+`),
+    acceptance_criteria: [
+      'JSON string of array: [{"id":"ac-1","text":"Given... When... Then...","isChecked":false}]',
+      "Write 3-8 criteria per ticket in Given/When/Then format.",
+      'Example: [{"id":"ac-1","text":"Given a user on the login page, When they click Sign in with Google, Then they are redirected to Google OAuth consent screen","isChecked":false}]',
+      "Use unique IDs (ac-1, ac-2, etc.). Set isChecked to false for new tickets. Max 10000 chars total."
+    ].join(`
+`),
+    tags: "Apply 2-5 tags per ticket after creation using set_ticket_tags. Use lowercase-kebab-case. Common categories: feature area (auth, billing), technology (react, api), work type (feature, bug, refactor). Create missing tags with create_tag first.",
+    ticket_type: "Always set typeSlug when creating tickets. Common types: feature, bug, task, improvement. Use list_ticket_types to see project-specific types."
+  },
   categories: {
     "Organization & Context": {
       tools: ["list_organizations", "set_organization", "get_current_organization", "list_organization_members", "get_member_profile", "get_my_profile"],
@@ -29234,19 +29455,21 @@ var TOOL_INDEX = {
     }
   },
   common_workflows: {
-    "Create a ticket": "list_statuses → list_priorities → list_sizes → create_ticket",
-    "Move through workflow": "get_available_transitions → move_ticket (or complete_ticket)",
-    "Sprint planning": "create_release → list_tickets (backlog) → assign_tickets_to_release",
+    "Create a high-quality ticket": "list_statuses + list_priorities + list_sizes + list_ticket_types + list_tags (cache IDs) → find_similar_tickets (check duplicates) → create_ticket (with description, acceptanceCriteria, typeSlug) → set_ticket_tags (add 2-5 tags)",
+    "AI-assisted ticket creation": "check_clarity → polish_title → generate_description → suggest_attributes → create_ticket → set_ticket_tags",
+    "Move through workflow": "get_available_transitions → move_ticket (or complete_ticket / abandon_ticket)",
+    "Sprint planning": "create_release → list_backlog_tickets → assign_tickets_to_release",
     "Daily standup": "get_my_tickets + get_overdue_tickets + get_tickets_due_soon",
-    "AI-assisted creation": "polish_title → generate_description → suggest_attributes → create_ticket",
-    "Bulk cleanup": "list_tickets (filter) → batch_complete_tickets or batch_move_tickets"
+    "Release shipping": "get_release_tickets (verify all complete) → mark_release_shipped",
+    "Bulk cleanup": "list_tickets (filter) → batch_complete_tickets or batch_move_tickets",
+    "Team workload review": "get_member_analytics + get_distribution_analytics"
   }
 };
 var helpTools = [
   {
     tool: {
       name: "get_help",
-      description: "Get a categorized index of all available Kanbo MCP tools and common workflows. Call this first to understand what capabilities are available.",
+      description: "Get the full Kanbo tool index, content quality guidelines, and multi-step workflows. Call this to understand available capabilities, how to create high-quality tickets, or which tools to chain together. Includes guidelines for descriptions, acceptance criteria, and tags.",
       inputSchema: {
         type: "object",
         properties: {
@@ -29322,8 +29545,10 @@ class ToolRegistryImpl {
   }
 }
 var toolRegistry = new ToolRegistryImpl;
-var toolLogger = logger.withCategory(LogCategory.STARTUP);
-toolLogger.info({ toolCount: toolRegistry.tools.length }, "Tools registered");
+function logToolRegistration() {
+  const toolLogger = logger.withCategory(LogCategory.STARTUP);
+  toolLogger.info({ toolCount: toolRegistry.tools.length }, "Tools registered");
+}
 
 // src/server.ts
 var serverLogger = logger.withCategory(LogCategory.SYSTEM);
@@ -29338,19 +29563,31 @@ function createMCPServer() {
     instructions: [
       "Kanbo MCP Server — AI-native project management.",
       "",
-      "GETTING STARTED:",
-      "1. Call list_organizations to see available orgs",
-      "2. Call set_organization to set the active org context",
-      "3. Call list_projects to discover projects",
+      "DOMAIN MODEL:",
+      "Organization → Projects → Tickets. Tickets live on a Board (active columns), in Backlog, or in Completed/Abandoned areas.",
+      "Each ticket has: title, description (markdown), status, priority, size, type, tags, assignee, acceptance criteria, due date, release, and parent (for subtasks).",
+      "Workflow transitions control which status moves are valid. Tags, priorities, sizes, and types are project-level configuration.",
+      "",
+      "SETUP (required before other calls):",
+      "1. list_organizations → set_organization (sets active org context)",
+      "2. list_projects → pick a project",
+      "3. Cache IDs for the session: list_statuses + list_priorities + list_sizes + list_ticket_types + list_tags",
       "",
-      "COMMON WORKFLOWS:",
-      "- Create ticket: get statusId from list_statuses, priorityId from list_priorities, sizeId from list_sizes, then call create_ticket",
-      "- Move ticket: call move_ticket with toStatusId (check get_available_transitions for valid moves)",
-      "- Complete ticket: call complete_ticket",
-      "- Find my work: call get_my_tickets",
-      "- Sprint planning: create_release, then assign_tickets_to_release",
+      "CREATING HIGH-QUALITY TICKETS:",
+      "Every ticket should have: title, statusId, priorityId, sizeId, typeSlug, description (markdown with ## headings), acceptanceCriteria (Given/When/Then JSON), and tags.",
+      "Description: Use markdown — ## Requirements, ## Technical Notes, bullet points, **bold** for key terms, `code` for identifiers. Max 5000 chars.",
+      'Acceptance criteria: JSON array of [{"id":"ac-1","text":"Given X, When Y, Then Z","isChecked":false}]. Include 3-8 criteria.',
+      "Tags: After create_ticket, call set_ticket_tags (use list_tags first; create missing tags with create_tag).",
+      "Duplicate check: Call find_similar_tickets before creating to avoid duplicates.",
       "",
-      "TOOL INDEX: Call get_help for a full categorized list of all available tools."
+      "WORKFLOWS:",
+      "- Create ticket: cache lookups → find_similar_tickets → create_ticket (with description + acceptanceCriteria + typeSlug) → set_ticket_tags",
+      "- AI-assisted: check_clarity → polish_title → generate_description → suggest_attributes → create_ticket → set_ticket_tags",
+      "- Move ticket: get_available_transitions → move_ticket (or complete_ticket / abandon_ticket)",
+      "- Sprint planning: create_release → list_backlog_tickets → assign_tickets_to_release",
+      "- Daily standup: get_my_tickets + get_overdue_tickets + get_tickets_due_soon",
+      "",
+      "TOOL INDEX: Call get_help for full tool list, content quality guidelines, and workflow chains."
     ].join(`
 `)
   });
@@ -29400,6 +29637,7 @@ function createMCPServer() {
   return server;
 }
 async function startStdioServer() {
+  logToolRegistration();
   serverLogger.info("Starting in stdio mode");
   if (!CONFIG.KANBO_API_KEY) {
     serverLogger.fatal("KANBO_API_KEY environment variable is required");
@@ -43819,6 +44057,9 @@ async function handleCliCommand(command) {
     case "whoami":
       await Promise.resolve().then(() => (init_whoami(), exports_whoami)).then((m) => m.whoami());
       return true;
+    case "install":
+      await Promise.resolve().then(() => (init_install(), exports_install)).then((m) => m.install());
+      return true;
     case "help":
     case "--help":
     case "-h":
@@ -43842,7 +44083,8 @@ function showHelp() {
 
   Commands:
     (none)      Start the MCP server (default)
-    login       Authenticate via browser OAuth
+    login       Authenticate via browser OAuth + register MCP server
+    install     Register MCP server with detected editors
     logout      Remove stored credentials
     whoami      Show current authentication status
     help        Show this help message
@@ -43856,7 +44098,8 @@ function showHelp() {
     PORT              HTTP server port (default: 8081)
 
   Examples:
-    kanbo-mcp login      # Authenticate via browser
+    kanbo-mcp login      # Authenticate + auto-register MCP server
+    kanbo-mcp install    # Register MCP server with editors
     kanbo-mcp            # Start MCP server
     kanbo-mcp whoami     # Check auth status
 `);