agentool 1.1.0 → 1.1.1

package/dist/chunk-NTGDU5X3.js

@@ -0,0 +1,67 @@
+import {
+  pathExists,
+  writeTextContent
+} from "./chunk-PWBVB6MN.js";
+import {
+  expandPath
+} from "./chunk-I3ONDY7P.js";
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
+
+// src/write/index.ts
+import { tool } from "ai";
+import { z } from "zod";
+
+// src/write/prompt.ts
+function getPrompt() {
+  return `Write text content to a file, creating parent directories as needed. If the file already exists it is overwritten entirely.
+
+Supports absolute paths, relative paths, and tilde (~) expansion.
+
+## When to Use
+- To create new files that don't exist yet
+- To completely rewrite an existing file's content
+- When the changes are so extensive that targeted editing would be impractical
+
+## When NOT to Use
+- To make small, targeted changes to an existing file \u2014 use the file editing tool instead (it only changes what you specify and is less error-prone)
+- Prefer the editing tool for modifications; reserve this tool for creating new files or complete rewrites
+
+## Usage Guidelines
+- This tool overwrites the entire file \u2014 make sure you include all desired content, not just the changes
+- Parent directories are created automatically if they don't exist
+- Read the existing file first before overwriting it, so you don't accidentally lose content`;
+}
+
+// src/write/index.ts
+function createWrite(config = {}) {
+  const cwd = config.cwd ?? process.cwd();
+  return tool({
+    description: config.description ?? getPrompt(),
+    inputSchema: z.object({
+      file_path: z.string().describe("The absolute path to the file to write (must be absolute, not relative)"),
+      content: z.string().describe("Text content to write to the file")
+    }),
+    execute: async ({ file_path, content }) => {
+      try {
+        const absolutePath = expandPath(file_path, cwd);
+        const existed = await pathExists(absolutePath);
+        await writeTextContent(absolutePath, content);
+        const bytes = Buffer.byteLength(content, "utf-8");
+        const verb = existed ? "Updated" : "Created";
+        return `${verb} file: ${absolutePath} (${bytes} bytes)`;
+      } catch (error) {
+        const message = extractErrorMessage(error);
+        return `Error [write]: Failed to write file: ${message}`;
+      }
+    }
+  });
+}
+var write = createWrite();
+
+export {
+  getPrompt,
+  createWrite,
+  write
+};

package/dist/{chunk-ONBH74ZV.cjs → chunk-OYLTQJXT.cjs}

@@ -1,14 +1,18 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
+var _chunkBIAODQ2Pcjs = require('./chunk-BIAODQ2P.cjs');
+
+
 var _chunkQZ5GS6HWcjs = require('./chunk-QZ5GS6HW.cjs');
 
+
+var _chunkKONXT2SFcjs = require('./chunk-KONXT2SF.cjs');
+
 // src/diff/index.ts
-var _promises = require('fs/promises');
 var _ai = require('ai');
 var _zod = require('zod');
 
 // src/shared/diff.ts
-
 var _diff = require('diff');
 function diffStrings(oldContent, newContent, options) {
   if (oldContent === newContent) {
@@ -29,8 +33,8 @@ function diffStrings(oldContent, newContent, options) {
 }
 async function diffFiles(oldFilePath, newFilePath, options) {
   const [oldContent, newContent] = await Promise.all([
-    _promises.readFile.call(void 0, oldFilePath, "utf-8"),
-    _promises.readFile.call(void 0, newFilePath, "utf-8")
+    _chunkBIAODQ2Pcjs.readTextContent.call(void 0, oldFilePath),
+    _chunkBIAODQ2Pcjs.readTextContent.call(void 0, newFilePath)
   ]);
   return diffStrings(oldContent, newContent, {
     ...options,
@@ -39,11 +43,30 @@ async function diffFiles(oldFilePath, newFilePath, options) {
   });
 }
 
+// src/diff/prompt.ts
+function getPrompt() {
+  return `Generate a unified diff between two files or two strings.
+
+Supports three modes:
+1. **Two file paths**: \`file_path\` + \`other_file_path\` \u2014 compares the contents of both files
+2. **Two strings**: \`old_content\` + \`new_content\` \u2014 compares the provided strings directly
+3. **File + string**: \`file_path\` + \`old_content\` or \`new_content\` \u2014 compares a file against provided content
+
+## When to Use
+- To preview what changes would look like before making edits
+- To compare two versions of a file or text
+- To generate a diff for review or documentation purposes
+
+## When NOT to Use
+- To actually apply changes to a file \u2014 use the file editing tool instead
+- To read file contents \u2014 use the file reading tool instead`;
+}
+
 // src/diff/index.ts
 function createDiff(config = {}) {
   const cwd = _nullishCoalesce(config.cwd, () => ( process.cwd()));
   return _ai.tool.call(void 0, {
-    description: "Generate a unified diff between two files or two strings. Provide file_path + other_file_path to compare files, or old_content + new_content to compare strings. You can also provide file_path with old_content or new_content to compare a file against provided content.",
+    description: _nullishCoalesce(config.description, () => ( getPrompt())),
     inputSchema: _zod.z.object({
       file_path: _zod.z.string().optional().describe("Path to the first file (absolute or relative to cwd)"),
       other_file_path: _zod.z.string().optional().describe("Path to the second file (absolute or relative to cwd)"),
@@ -62,7 +85,7 @@ function createDiff(config = {}) {
         }
         if (file_path && (old_content !== void 0 || new_content !== void 0)) {
           const resolvedPath = _chunkQZ5GS6HWcjs.expandPath.call(void 0, file_path, cwd);
-          const fileContent = await _promises.readFile.call(void 0, resolvedPath, "utf-8");
+          const fileContent = await _chunkBIAODQ2Pcjs.readTextContent.call(void 0, resolvedPath);
           if (old_content !== void 0) {
             return diffStrings(old_content, fileContent, {
               oldLabel: "provided",
@@ -76,7 +99,7 @@ function createDiff(config = {}) {
         }
         return "Error [diff]: Insufficient parameters. Provide either: (1) file_path + other_file_path, (2) old_content + new_content, or (3) file_path + old_content/new_content.";
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
         return `Error [diff]: ${msg}`;
       }
     }
@@ -87,4 +110,5 @@ var diff = createDiff();
 
 
 
-exports.createDiff = createDiff; exports.diff = diff;
+
+exports.getPrompt = getPrompt; exports.createDiff = createDiff; exports.diff = diff;

package/dist/{chunk-6PQLFDGT.js → chunk-PWBVB6MN.js}

@@ -1,6 +1,6 @@
 // src/shared/file.ts
 import { createReadStream } from "fs";
-import { mkdir, readFile, stat, writeFile } from "fs/promises";
+import { mkdir, readFile, readdir, stat, unlink, writeFile } from "fs/promises";
 import { dirname } from "path";
 var FAST_PATH_MAX_SIZE = 10 * 1024 * 1024;
 function addLineNumbers({
@@ -25,6 +25,18 @@ async function pathExists(path) {
     return false;
   }
 }
+async function readTextContent(filePath) {
+  return readFile(filePath, "utf-8");
+}
+async function listDirectory(dirPath) {
+  return readdir(dirPath);
+}
+async function removeFile(filePath) {
+  await unlink(filePath);
+}
+async function getFileStats(filePath) {
+  return stat(filePath);
+}
 async function readFileInRange(filePath, offset = 0, maxLines) {
   const stats = await stat(filePath);
   if (stats.isDirectory()) {
@@ -113,5 +125,9 @@ export {
   addLineNumbers,
   writeTextContent,
   pathExists,
+  readTextContent,
+  listDirectory,
+  removeFile,
+  getFileStats,
   readFileInRange
 };

package/dist/{chunk-HNP7JDQC.cjs → chunk-RIGL3JTS.cjs}

@@ -3,13 +3,48 @@
 var _chunkMIYA7TNRcjs = require('./chunk-MIYA7TNR.cjs');
 
 
+var _chunkBIAODQ2Pcjs = require('./chunk-BIAODQ2P.cjs');
+
+
 
 var _chunkQZ5GS6HWcjs = require('./chunk-QZ5GS6HW.cjs');
 
+
+var _chunkKONXT2SFcjs = require('./chunk-KONXT2SF.cjs');
+
 // src/grep/index.ts
-var _promises = require('fs/promises');
 var _ai = require('ai');
 var _zod = require('zod');
+
+// src/grep/prompt.ts
+function getPrompt() {
+  return `Search file contents using ripgrep. Supports regex patterns, context lines, and multiple output modes.
+
+## When to Use
+- To find where a function, variable, string, or pattern is used across files
+- To search for specific code patterns, error messages, or configuration values
+- To count occurrences of a pattern across a codebase
+
+## When NOT to Use
+- To find files by name/extension \u2014 use the dedicated file search tool instead
+- To read a specific file \u2014 use the file reading tool instead
+- Don't use shell commands (grep, rg) for content search when this tool is available
+
+## Output Modes
+- \`files_with_matches\` (default): Returns file paths containing matches, sorted by modification time. Best for discovering which files contain a pattern.
+- \`content\`: Returns matching lines with optional context. Supports \`-A\` (after), \`-B\` (before), \`-C\` (context) for surrounding lines and \`-n\` for line numbers (default: true).
+- \`count\`: Returns match counts per file with totals.
+
+## Usage Guidelines
+- Uses ripgrep regex syntax (not grep). Literal braces need escaping: use \`interface\\{\\}\` to find \`interface{}\`
+- Filter files with the \`glob\` parameter (e.g., "*.js", "*.{ts,tsx}") or \`type\` parameter (e.g., "js", "py")
+- Default head_limit is 250 entries. Pass \`head_limit: 0\` for unlimited (use sparingly \u2014 large results waste context)
+- Use \`offset\` to paginate through large result sets
+- Enable \`multiline: true\` for patterns that span lines (e.g., \`struct \\{[\\s\\S]*?field\`)
+- Use \`-i: true\` for case-insensitive search`;
+}
+
+// src/grep/index.ts
 var VCS_DIRS = [".git", ".svn", ".hg", ".bzr", ".jj", ".sl"];
 var DEFAULT_HEAD_LIMIT = 250;
 function applyHeadLimit(items, limit, offset = 0) {
@@ -48,7 +83,7 @@ function parseGlobPatterns(globFilter) {
 function createGrep(config = {}) {
   const cwd = _nullishCoalesce(config.cwd, () => ( process.cwd()));
   return _ai.tool.call(void 0, {
-    description: 'Search file contents using ripgrep. Supports regex patterns, context lines, and three output modes: "content" (matching lines), "files_with_matches" (file paths), and "count" (match counts).',
+    description: _nullishCoalesce(config.description, () => ( getPrompt())),
     inputSchema: _zod.z.object({
       pattern: _zod.z.string().describe("The regular expression pattern to search for in file contents"),
       path: _zod.z.string().optional().describe("File or directory to search in (rg PATH). Defaults to current working directory."),
@@ -132,7 +167,7 @@ function createGrep(config = {}) {
 
 Total: ${totalMatches} matches in ${fileCount} files` + truncationSuffix(appliedLimit2, offset);
         }
-        const stats = await Promise.allSettled(results.map((f) => _promises.stat.call(void 0, f)));
+        const stats = await Promise.allSettled(results.map((f) => _chunkBIAODQ2Pcjs.getFileStats.call(void 0, f)));
         const sorted = results.map((fp, i) => {
           const r = stats[i];
           const mt = r.status === "fulfilled" ? _nullishCoalesce(r.value.mtimeMs, () => ( 0)) : 0;
@@ -145,7 +180,7 @@ Total: ${totalMatches} matches in ${fileCount} files` + truncationSuffix(applied
         const relative = items.map((f) => _chunkQZ5GS6HWcjs.toRelativePath.call(void 0, f, cwd));
         return relative.join("\n") + truncationSuffix(appliedLimit, offset);
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
         return `Error [grep]: Failed to search: ${msg}`;
       }
     }
@@ -156,4 +191,5 @@ var grep = createGrep();
 
 
 
-exports.createGrep = createGrep; exports.grep = grep;
+
+exports.getPrompt = getPrompt; exports.createGrep = createGrep; exports.grep = grep;

package/dist/chunk-SFDZRLSX.cjs

@@ -0,0 +1,91 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+
+
+
+
+var _chunkVQSWMGG7cjs = require('./chunk-VQSWMGG7.cjs');
+
+
+var _chunkKONXT2SFcjs = require('./chunk-KONXT2SF.cjs');
+
+// src/task-create/index.ts
+var _ai = require('ai');
+var _zod = require('zod');
+var _path = require('path');
+
+// src/task-create/prompt.ts
+function getPrompt() {
+  return `Create a new task to track work. Tasks are stored as JSON and support status tracking, dependencies, and metadata.
+
+## When to Use
+- Complex multi-step tasks requiring 3 or more distinct steps
+- Non-trivial work that benefits from progress tracking
+- When the user provides a list of things to be done
+- After receiving new instructions \u2014 capture requirements as tasks immediately
+- When planning mode is active \u2014 create a task list to track the plan
+
+## When NOT to Use
+- Single, straightforward tasks that need no tracking
+- Trivial work completable in fewer than 3 simple steps
+- Purely conversational or informational requests
+If there is only one simple task, just do it directly instead of creating a task for it.
+
+## Task Fields
+- **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
+- **description**: Detailed explanation of what needs to be done
+- **metadata** (optional): Arbitrary key-value pairs to attach to the task
+
+All tasks are created with status \`pending\`, empty \`blocks\` and \`blockedBy\` arrays.
+
+## Tips
+- Create tasks with clear, specific subjects that describe the desired outcome
+- After creating tasks, set up dependencies (blocks/blockedBy) if tasks must run in order
+- Check the task list first to avoid creating duplicate tasks
+- When starting work on a task, update its status to \`in_progress\` before beginning
+- After completing a task, mark it \`completed\` and check for newly unblocked tasks`;
+}
+
+// src/task-create/index.ts
+function createTaskCreate(config = {}) {
+  const cwd = _nullishCoalesce(config.cwd, () => ( process.cwd()));
+  const tasksFile = _nullishCoalesce(config.tasksFile, () => ( _path.join.call(void 0, cwd, ".agentool", "tasks.json")));
+  return _ai.tool.call(void 0, {
+    description: _nullishCoalesce(config.description, () => ( getPrompt())),
+    inputSchema: _zod.z.object({
+      subject: _zod.z.string().describe("A brief title for the task"),
+      description: _zod.z.string().describe("What needs to be done"),
+      metadata: _zod.z.record(_zod.z.string(), _zod.z.unknown()).optional().describe("Arbitrary metadata to attach to the task")
+    }),
+    execute: async ({ subject, description, metadata }) => {
+      try {
+        const tasks = await _chunkVQSWMGG7cjs.loadTasks.call(void 0, tasksFile);
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        const entry = {
+          id: _chunkVQSWMGG7cjs.generateId.call(void 0, ),
+          subject,
+          description,
+          status: "pending",
+          blocks: [],
+          blockedBy: [],
+          metadata,
+          createdAt: now,
+          updatedAt: now
+        };
+        tasks.push(entry);
+        await _chunkVQSWMGG7cjs.saveTasks.call(void 0, tasksFile, tasks);
+        return `Created task ${entry.id}.
+${_chunkVQSWMGG7cjs.formatTask.call(void 0, entry)}`;
+      } catch (error) {
+        const msg = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
+        return `Error [task-create]: ${msg}`;
+      }
+    }
+  });
+}
+var taskCreate = createTaskCreate();
+
+
+
+
+
+exports.getPrompt = getPrompt; exports.createTaskCreate = createTaskCreate; exports.taskCreate = taskCreate;

package/dist/{chunk-ZFQZWXOI.cjs → chunk-T6STO7PS.cjs}

@@ -2,17 +2,67 @@
 
 
 
-var _chunkL5JH4I77cjs = require('./chunk-L5JH4I77.cjs');
+var _chunkVQSWMGG7cjs = require('./chunk-VQSWMGG7.cjs');
+
+
+var _chunkKONXT2SFcjs = require('./chunk-KONXT2SF.cjs');
 
 // src/task-update/index.ts
 var _ai = require('ai');
 var _zod = require('zod');
 var _path = require('path');
+
+// src/task-update/prompt.ts
+function getPrompt() {
+  return `Update a task by its ID. Can change status, subject, description, owner, metadata, and dependency relationships.
+
+## When to Use
+
+**Marking tasks as completed:**
+- When you have fully completed the work described in a task
+- ONLY mark a task as completed when the work is truly done
+- If you encounter errors or blockers, keep the task as \`in_progress\`
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+
+**Marking tasks as in progress:**
+- When you begin working on a task, set it to \`in_progress\` immediately
+
+**Deleting tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to \`deleted\` permanently removes the task from the list
+
+**Updating details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Status Workflow
+Status progresses: \`pending\` \u2192 \`in_progress\` \u2192 \`completed\`
+Use \`deleted\` to remove a task permanently.
+
+## Fields You Can Update
+- **status**: pending, in_progress, completed, or deleted
+- **subject**: Change the task title
+- **description**: Change the task description
+- **owner**: Assign or reassign the task
+- **activeForm**: Present continuous form shown when in_progress (e.g., "Running tests")
+- **addBlocks**: Add task IDs that cannot start until this task completes
+- **addBlockedBy**: Add task IDs that must complete before this task can start
+- **metadata**: Merge key-value pairs into the task (set a key to null to delete it)
+
+## Tips
+- After completing a task, check the task list for newly unblocked work
+- Use dependencies (blocks/blockedBy) to enforce execution order when tasks depend on each other`;
+}
+
+// src/task-update/index.ts
 function createTaskUpdate(config = {}) {
   const cwd = _nullishCoalesce(config.cwd, () => ( process.cwd()));
   const tasksFile = _nullishCoalesce(config.tasksFile, () => ( _path.join.call(void 0, cwd, ".agentool", "tasks.json")));
   return _ai.tool.call(void 0, {
-    description: "Update a task by its ID. Can change status, subject, description, owner, metadata, and dependency relationships.",
+    description: _nullishCoalesce(config.description, () => ( getPrompt())),
     inputSchema: _zod.z.object({
       taskId: _zod.z.string().describe("The ID of the task to update"),
       subject: _zod.z.string().optional().describe("New subject for the task"),
@@ -26,7 +76,7 @@ function createTaskUpdate(config = {}) {
     }),
     execute: async (input) => {
       try {
-        const tasks = await _chunkL5JH4I77cjs.loadTasks.call(void 0, tasksFile);
+        const tasks = await _chunkVQSWMGG7cjs.loadTasks.call(void 0, tasksFile);
         const idx = tasks.findIndex((t) => t.id === input.taskId);
         if (idx === -1) return `Error [task-update]: Task "${input.taskId}" not found.`;
         const entry = tasks[idx];
@@ -57,11 +107,11 @@ function createTaskUpdate(config = {}) {
         }
         entry.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
         tasks[idx] = entry;
-        await _chunkL5JH4I77cjs.saveTasks.call(void 0, tasksFile, tasks);
+        await _chunkVQSWMGG7cjs.saveTasks.call(void 0, tasksFile, tasks);
         return `Updated task ${input.taskId}.
-${_chunkL5JH4I77cjs.formatTask.call(void 0, entry)}`;
+${_chunkVQSWMGG7cjs.formatTask.call(void 0, entry)}`;
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
         return `Error [task-update]: ${msg}`;
       }
     }
@@ -72,4 +122,5 @@ var taskUpdate = createTaskUpdate();
 
 
 
-exports.createTaskUpdate = createTaskUpdate; exports.taskUpdate = taskUpdate;
+
+exports.getPrompt = getPrompt; exports.createTaskUpdate = createTaskUpdate; exports.taskUpdate = taskUpdate;

package/dist/{chunk-LPV5CN2K.js → chunk-TI4ZZ3IJ.js}

@@ -1,9 +1,38 @@
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
+
 // src/http-request/index.ts
 import { tool } from "ai";
 import { z } from "zod";
+
+// src/http-request/prompt.ts
+function getPrompt(config = {}) {
+  const timeout = config.timeout ?? 3e4;
+  return `Make an HTTP request to a URL. Returns the raw response status, headers, and body as JSON.
+
+Supports GET, POST, PUT, PATCH, DELETE, and HEAD methods.
+
+## When to Use
+- For API interactions: REST calls, webhook triggers, service health checks
+- When you need full control over HTTP method, headers, and request body
+- When you need the raw response (status codes, headers) not just content
+
+## When NOT to Use
+- To read a web page for its content \u2014 use the web fetch tool instead (it converts HTML to markdown)
+- To search the web \u2014 use the web search tool instead
+
+## Usage Guidelines
+- Default timeout: ${timeout}ms. Override with the timeout parameter.
+- Request body is sent for POST, PUT, and PATCH methods
+- Response is returned as JSON with status, statusText, headers, and body fields
+- Default headers from config are merged with per-request headers (per-request takes precedence)`;
+}
+
+// src/http-request/index.ts
 function createHttpRequest(config = {}) {
   return tool({
-    description: "Make an HTTP request to a URL. Returns the response status, headers, and body. Use this for API interactions, webhook calls, and service health checks. Unlike web-fetch, this returns raw response data without markdown conversion.",
+    description: config.description ?? getPrompt(config),
     inputSchema: z.object({
       method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]).describe("HTTP method"),
       url: z.string().describe("The URL to send the request to"),
@@ -44,7 +73,7 @@ function createHttpRequest(config = {}) {
         if (error instanceof Error && error.name === "AbortError") {
           return `Error [http-request]: Request timed out after ${effectiveTimeout}ms for ${method} ${url}. Try increasing the timeout or verify the server is responsive.`;
         }
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = extractErrorMessage(error);
         return `Error [http-request]: ${method} ${url} failed: ${msg}. Verify the URL is correct and the server is reachable.`;
       }
     }
@@ -53,6 +82,7 @@ function createHttpRequest(config = {}) {
 var httpRequest = createHttpRequest();
 
 export {
+  getPrompt,
   createHttpRequest,
   httpRequest
 };

package/dist/{chunk-S7IVHOA6.js → chunk-TM5L4HA5.js}

@@ -2,17 +2,67 @@ import {
   formatTask,
   loadTasks,
   saveTasks
-} from "./chunk-E6NBEYZD.js";
+} from "./chunk-VHLY7LQE.js";
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
 
 // src/task-update/index.ts
 import { tool } from "ai";
 import { z } from "zod";
 import { join } from "path";
+
+// src/task-update/prompt.ts
+function getPrompt() {
+  return `Update a task by its ID. Can change status, subject, description, owner, metadata, and dependency relationships.
+
+## When to Use
+
+**Marking tasks as completed:**
+- When you have fully completed the work described in a task
+- ONLY mark a task as completed when the work is truly done
+- If you encounter errors or blockers, keep the task as \`in_progress\`
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+
+**Marking tasks as in progress:**
+- When you begin working on a task, set it to \`in_progress\` immediately
+
+**Deleting tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to \`deleted\` permanently removes the task from the list
+
+**Updating details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Status Workflow
+Status progresses: \`pending\` \u2192 \`in_progress\` \u2192 \`completed\`
+Use \`deleted\` to remove a task permanently.
+
+## Fields You Can Update
+- **status**: pending, in_progress, completed, or deleted
+- **subject**: Change the task title
+- **description**: Change the task description
+- **owner**: Assign or reassign the task
+- **activeForm**: Present continuous form shown when in_progress (e.g., "Running tests")
+- **addBlocks**: Add task IDs that cannot start until this task completes
+- **addBlockedBy**: Add task IDs that must complete before this task can start
+- **metadata**: Merge key-value pairs into the task (set a key to null to delete it)
+
+## Tips
+- After completing a task, check the task list for newly unblocked work
+- Use dependencies (blocks/blockedBy) to enforce execution order when tasks depend on each other`;
+}
+
+// src/task-update/index.ts
 function createTaskUpdate(config = {}) {
   const cwd = config.cwd ?? process.cwd();
   const tasksFile = config.tasksFile ?? join(cwd, ".agentool", "tasks.json");
   return tool({
-    description: "Update a task by its ID. Can change status, subject, description, owner, metadata, and dependency relationships.",
+    description: config.description ?? getPrompt(),
     inputSchema: z.object({
       taskId: z.string().describe("The ID of the task to update"),
       subject: z.string().optional().describe("New subject for the task"),
@@ -61,7 +111,7 @@ function createTaskUpdate(config = {}) {
         return `Updated task ${input.taskId}.
 ${formatTask(entry)}`;
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = extractErrorMessage(error);
         return `Error [task-update]: ${msg}`;
       }
     }
@@ -70,6 +120,7 @@ ${formatTask(entry)}`;
 var taskUpdate = createTaskUpdate();
 
 export {
+  getPrompt,
   createTaskUpdate,
   taskUpdate
 };