agentool 1.1.0 → 1.1.1

package/dist/ask-user/index.cjs

@@ -1,8 +1,11 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
 
-var _chunk3EPGFWZVcjs = require('../chunk-3EPGFWZV.cjs');
 
+var _chunkKUFZFNPTcjs = require('../chunk-KUFZFNPT.cjs');
+require('../chunk-KONXT2SF.cjs');
 
 
-exports.askUser = _chunk3EPGFWZVcjs.askUser; exports.createAskUser = _chunk3EPGFWZVcjs.createAskUser;
+
+
+exports.askUser = _chunkKUFZFNPTcjs.askUser; exports.askUserPrompt = _chunkKUFZFNPTcjs.getPrompt; exports.createAskUser = _chunkKUFZFNPTcjs.createAskUser;

package/dist/ask-user/index.d.cts

@@ -1,6 +1,13 @@
 import * as ai from 'ai';
 import { B as BaseToolConfig } from '../types-3QPDuCXN.cjs';
 
+/**
+ * Generate the description prompt for the ask-user tool.
+ *
+ * @returns The full description string for the ask-user tool.
+ */
+declare function getPrompt(): string;
+
 /**
  * Configuration for the ask-user tool.
  * Extends {@link BaseToolConfig} with an optional callback for receiving user input.
@@ -23,6 +30,8 @@ interface AskUserConfig extends BaseToolConfig {
      * @returns The user's response string
      */
     onQuestion?: (question: string, options?: string[]) => Promise<string>;
+    /** Override the default tool description. */
+    description?: string;
 }
 /**
  * Creates an ask-user tool instance with the given configuration.
@@ -65,4 +74,4 @@ declare const askUser: ai.Tool<{
     options?: string[] | undefined;
 }, string>;
 
-export { type AskUserConfig, askUser, createAskUser };
+export { type AskUserConfig, askUser, getPrompt as askUserPrompt, createAskUser };

package/dist/ask-user/index.d.ts

@@ -1,6 +1,13 @@
 import * as ai from 'ai';
 import { B as BaseToolConfig } from '../types-3QPDuCXN.js';
 
+/**
+ * Generate the description prompt for the ask-user tool.
+ *
+ * @returns The full description string for the ask-user tool.
+ */
+declare function getPrompt(): string;
+
 /**
  * Configuration for the ask-user tool.
  * Extends {@link BaseToolConfig} with an optional callback for receiving user input.
@@ -23,6 +30,8 @@ interface AskUserConfig extends BaseToolConfig {
      * @returns The user's response string
      */
     onQuestion?: (question: string, options?: string[]) => Promise<string>;
+    /** Override the default tool description. */
+    description?: string;
 }
 /**
  * Creates an ask-user tool instance with the given configuration.
@@ -65,4 +74,4 @@ declare const askUser: ai.Tool<{
     options?: string[] | undefined;
 }, string>;
 
-export { type AskUserConfig, askUser, createAskUser };
+export { type AskUserConfig, askUser, getPrompt as askUserPrompt, createAskUser };

package/dist/ask-user/index.js

@@ -1,8 +1,11 @@
 import {
   askUser,
-  createAskUser
-} from "../chunk-HDKXSKMO.js";
+  createAskUser,
+  getPrompt
+} from "../chunk-L7R4UZSK.js";
+import "../chunk-X6ZY2KFU.js";
 export {
   askUser,
+  getPrompt as askUserPrompt,
   createAskUser
 };

package/dist/bash/index.cjs

@@ -1,8 +1,11 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
 
-var _chunkSUSAPI5Wcjs = require('../chunk-SUSAPI5W.cjs');
 
+var _chunkCXBWF5ONcjs = require('../chunk-CXBWF5ON.cjs');
+require('../chunk-KONXT2SF.cjs');
 
 
-exports.bash = _chunkSUSAPI5Wcjs.bash; exports.createBash = _chunkSUSAPI5Wcjs.createBash;
+
+
+exports.bash = _chunkCXBWF5ONcjs.bash; exports.bashPrompt = _chunkCXBWF5ONcjs.getPrompt; exports.createBash = _chunkCXBWF5ONcjs.createBash;

package/dist/bash/index.d.cts

@@ -1,6 +1,17 @@
 import * as ai from 'ai';
 import { T as TimeoutConfig } from '../types-3QPDuCXN.cjs';
 
+/**
+ * Generate the description prompt for the bash tool based on its configuration.
+ *
+ * The returned string is used as the tool's `description` field in the
+ * Vercel AI SDK tool definition, providing the model with behavioral guidance.
+ *
+ * @param config - The same config passed to {@link createBash}.
+ * @returns The full description string for the bash tool.
+ */
+declare function getPrompt(config?: Pick<BashConfig, 'timeout' | 'shell'>): string;
+
 /**
  * Configuration for the bash tool.
  * Extends {@link TimeoutConfig} with an optional shell binary path.
@@ -14,6 +25,8 @@ import { T as TimeoutConfig } from '../types-3QPDuCXN.cjs';
 interface BashConfig extends TimeoutConfig {
     /** Shell binary to use. Defaults to `$SHELL` or `/bin/bash`. */
     shell?: string;
+    /** Override the default tool description. */
+    description?: string;
 }
 /**
  * Creates a bash tool that executes shell commands via {@link executeShell}.
@@ -60,4 +73,4 @@ declare const bash: ai.Tool<{
     description?: string | undefined;
 }, string>;
 
-export { type BashConfig, bash, createBash };
+export { type BashConfig, bash, getPrompt as bashPrompt, createBash };

package/dist/bash/index.d.ts

@@ -1,6 +1,17 @@
 import * as ai from 'ai';
 import { T as TimeoutConfig } from '../types-3QPDuCXN.js';
 
+/**
+ * Generate the description prompt for the bash tool based on its configuration.
+ *
+ * The returned string is used as the tool's `description` field in the
+ * Vercel AI SDK tool definition, providing the model with behavioral guidance.
+ *
+ * @param config - The same config passed to {@link createBash}.
+ * @returns The full description string for the bash tool.
+ */
+declare function getPrompt(config?: Pick<BashConfig, 'timeout' | 'shell'>): string;
+
 /**
  * Configuration for the bash tool.
  * Extends {@link TimeoutConfig} with an optional shell binary path.
@@ -14,6 +25,8 @@ import { T as TimeoutConfig } from '../types-3QPDuCXN.js';
 interface BashConfig extends TimeoutConfig {
     /** Shell binary to use. Defaults to `$SHELL` or `/bin/bash`. */
     shell?: string;
+    /** Override the default tool description. */
+    description?: string;
 }
 /**
  * Creates a bash tool that executes shell commands via {@link executeShell}.
@@ -60,4 +73,4 @@ declare const bash: ai.Tool<{
     description?: string | undefined;
 }, string>;
 
-export { type BashConfig, bash, createBash };
+export { type BashConfig, bash, getPrompt as bashPrompt, createBash };

package/dist/bash/index.js

@@ -1,8 +1,11 @@
 import {
   bash,
-  createBash
-} from "../chunk-4YI2H55A.js";
+  createBash,
+  getPrompt
+} from "../chunk-TXZ3BMMR.js";
+import "../chunk-X6ZY2KFU.js";
 export {
   bash,
+  getPrompt as bashPrompt,
   createBash
 };

package/dist/{chunk-IEX4NOVN.cjs → chunk-2JBLVFB7.cjs}

@@ -1,9 +1,34 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }// src/tool-search/index.ts
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+
+var _chunkKONXT2SFcjs = require('./chunk-KONXT2SF.cjs');
+
+// src/tool-search/index.ts
 var _ai = require('ai');
 var _zod = require('zod');
+
+// src/tool-search/prompt.ts
+function getPrompt() {
+  return `Search for available tools by name or keyword. Returns matching tool names and their descriptions.
+
+Uses fuzzy matching \u2014 scores results by name and description relevance.
+
+## When to Use
+- To discover what tools are available when you're unsure which tool to use
+- To find the right tool for a specific task by searching with keywords
+
+## When NOT to Use
+- When you already know the tool name \u2014 just use it directly
+
+## Usage Guidelines
+- Requires a tools registry to be configured via createToolSearch({ tools: { ... } })
+- Returns up to \`max_results\` matches (default: 5), sorted by relevance
+- Matches against both tool names and descriptions`;
+}
+
+// src/tool-search/index.ts
 function createToolSearch(config = {}) {
   return _ai.tool.call(void 0, {
-    description: "Search for available tools by name or keyword. Returns matching tool names and descriptions.",
+    description: _nullishCoalesce(config.description, () => ( getPrompt())),
     inputSchema: _zod.z.object({
       query: _zod.z.string().describe("Query to find tools by name or keyword"),
       max_results: _zod.z.number().optional().default(5).describe("Max results to return")
@@ -34,7 +59,7 @@ function createToolSearch(config = {}) {
         }
         return scored.map((e) => `${e.name}: ${e.description}`).join("\n");
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
         return `Error [tool-search]: ${msg}`;
       }
     }
@@ -45,4 +70,5 @@ var toolSearch = createToolSearch();
 
 
 
-exports.createToolSearch = createToolSearch; exports.toolSearch = toolSearch;
+
+exports.getPrompt = getPrompt; exports.createToolSearch = createToolSearch; exports.toolSearch = toolSearch;

package/dist/{chunk-K77GC2QI.js → chunk-2JF3ZF2J.js}

@@ -1,6 +1,35 @@
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
+
 // src/context-compaction/index.ts
 import { tool, zodSchema } from "ai";
 import { z } from "zod";
+
+// src/context-compaction/prompt.ts
+function getPrompt(config = {}) {
+  const maxTokens = config.maxTokens ?? 4096;
+  return `Compact conversation history by summarizing older messages to reduce context size. Target budget: ${maxTokens} tokens.
+
+Requires a summarize callback to be configured \u2014 the application provides the summarization implementation.
+
+## When to Use
+- When the conversation is getting long and approaching context limits
+- When earlier messages contain details no longer relevant to the current task
+- To free up context space for new work without losing important context
+
+## When NOT to Use
+- When the conversation is still within budget \u2014 the tool returns early if already compact
+- When every message contains critical details that shouldn't be summarized
+- For persisting information long-term \u2014 use the memory tool instead
+
+## Usage Guidelines
+- Messages already within the token budget (${maxTokens} tokens, ~${maxTokens * 4} characters) are returned unchanged
+- The summarize callback receives all messages and should return a condensed summary
+- The result replaces the original messages with a single system message containing the summary`;
+}
+
+// src/context-compaction/index.ts
 var parametersSchema = z.object({
   messages: z.array(
     z.object({
@@ -14,7 +43,7 @@ var parametersSchema = z.object({
 });
 function createContextCompaction(config = {}) {
   return tool({
-    description: "Compact conversation history by summarizing older messages to reduce context size. Requires a summarize function in config. Returns compacted messages where total chars < maxTokens * 4.",
+    description: config.description ?? getPrompt(config),
     inputSchema: zodSchema(parametersSchema),
     execute: async ({
       messages,
@@ -45,7 +74,7 @@ function createContextCompaction(config = {}) {
           originalCount: messages.length
         });
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = extractErrorMessage(error);
         return `Error [context-compaction]: Summarization failed: ${msg}`;
       }
     }
@@ -54,6 +83,7 @@ function createContextCompaction(config = {}) {
 var contextCompaction = createContextCompaction();
 
 export {
+  getPrompt,
   createContextCompaction,
   contextCompaction
 };

package/dist/{chunk-UDIG7332.js → chunk-2WSZCOJP.js}

@@ -1,15 +1,50 @@
 import {
   executeRipgrep
 } from "./chunk-MJCAXASI.js";
+import {
+  getFileStats
+} from "./chunk-PWBVB6MN.js";
 import {
   expandPath,
   toRelativePath
 } from "./chunk-I3ONDY7P.js";
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
 
 // src/grep/index.ts
-import { stat } from "fs/promises";
 import { tool } from "ai";
 import { z } from "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 = config.cwd ?? process.cwd();
   return tool({
-    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: config.description ?? getPrompt(),
     inputSchema: z.object({
       pattern: z.string().describe("The regular expression pattern to search for in file contents"),
       path: 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) => stat(f)));
+        const stats = await Promise.allSettled(results.map((f) => getFileStats(f)));
         const sorted = results.map((fp, i) => {
           const r = stats[i];
           const mt = r.status === "fulfilled" ? r.value.mtimeMs ?? 0 : 0;
@@ -145,7 +180,7 @@ Total: ${totalMatches} matches in ${fileCount} files` + truncationSuffix(applied
         const relative = items.map((f) => toRelativePath(f, cwd));
         return relative.join("\n") + truncationSuffix(appliedLimit, offset);
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = extractErrorMessage(error);
         return `Error [grep]: Failed to search: ${msg}`;
       }
     }
@@ -154,6 +189,7 @@ Total: ${totalMatches} matches in ${fileCount} files` + truncationSuffix(applied
 var grep = createGrep();
 
 export {
+  getPrompt,
   createGrep,
   grep
 };

package/dist/chunk-3FT4ZPB2.cjs

@@ -0,0 +1,65 @@
+"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-list/index.ts
+var _ai = require('ai');
+var _zod = require('zod');
+var _path = require('path');
+
+// src/task-list/prompt.ts
+function getPrompt() {
+  return `List all tasks with their status, owner, and dependencies.
+
+## When to Use
+- To see what tasks are available to work on (status: pending, not blocked)
+- To check overall progress on the current work
+- To find tasks that are blocked and need dependencies resolved
+- After completing a task \u2014 check for newly unblocked work
+- Before creating new tasks \u2014 check for duplicates
+
+## Output Format
+Returns a summary of each non-deleted task:
+- **id**: Task identifier (use with task-get or task-update)
+- **status**: pending, in_progress, or completed
+- **subject**: Brief description of the task
+- **owner**: Who is assigned (if set)
+- **blockedBy**: Tasks that must complete before this one can start
+
+## Tips
+- Tasks with non-empty \`blockedBy\` lists cannot be started until their dependencies are resolved
+- Use task-get with a specific ID to see full details including description and metadata
+- After marking a task completed, call this tool to find the next available task`;
+}
+
+// src/task-list/index.ts
+function createTaskList(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({}),
+    execute: async () => {
+      try {
+        const tasks = await _chunkVQSWMGG7cjs.loadTasks.call(void 0, tasksFile);
+        const visible = tasks.filter((t) => t.status !== "deleted");
+        if (visible.length === 0) return "No tasks found.";
+        return visible.map(_chunkVQSWMGG7cjs.formatTaskSummary).join("\n");
+      } catch (error) {
+        const msg = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
+        return `Error [task-list]: ${msg}`;
+      }
+    }
+  });
+}
+var taskList = createTaskList();
+
+
+
+
+
+exports.getPrompt = getPrompt; exports.createTaskList = createTaskList; exports.taskList = taskList;

package/dist/{chunk-VLNDEVKS.js → chunk-3LGXZLBH.js}

@@ -1,12 +1,50 @@
+import {
+  listDirectory,
+  readTextContent,
+  removeFile,
+  writeTextContent
+} from "./chunk-PWBVB6MN.js";
 import {
   containsPathTraversal
 } from "./chunk-I3ONDY7P.js";
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
 
 // src/memory/index.ts
 import { tool } from "ai";
 import { z } from "zod";
-import { mkdir, readFile, readdir, unlink, writeFile } from "fs/promises";
 import { join } from "path";
+
+// src/memory/prompt.ts
+function getPrompt() {
+  return `File-based key-value memory store for persisting notes, context, or any text data across conversations.
+
+Entries are stored as individual .md files in the memory directory.
+
+## Operations
+- **write**: Store content under a key (creates or overwrites)
+- **read**: Retrieve content by key
+- **list**: List all stored keys
+- **delete**: Remove a key and its content
+
+## When to Use
+- To persist information that should survive across conversations or sessions
+- To store user preferences, project notes, or context summaries
+- To keep a running log of decisions, findings, or important details
+
+## When NOT to Use
+- For temporary data within a single conversation \u2014 just keep it in context
+- For structured task tracking \u2014 use the task management tools instead
+
+## Usage Guidelines
+- Keys are sanitized to prevent path traversal (no ../ allowed)
+- The \`key\` parameter is required for read, write, and delete operations
+- The \`content\` parameter is required for write operations
+- Use descriptive key names for easy discovery (e.g., "user-preferences", "project-architecture")`;
+}
+
+// src/memory/index.ts
 function sanitizeKey(key) {
   if (!key || key.trim() === "") {
     return { err: "Error [memory]: Key must not be empty." };
@@ -24,7 +62,7 @@ function createMemory(config = {}) {
   const cwd = config.cwd ?? process.cwd();
   const memoryDir = config.memoryDir ?? join(cwd, ".agentool", "memory");
   return tool({
-    description: "File-based key-value memory store. Use this to persist notes, context, or any text data across conversations. Supports write, read, list, and delete operations.",
+    description: config.description ?? getPrompt(),
     inputSchema: z.object({
       action: z.enum(["read", "write", "list", "delete"]).describe(
         "The operation to perform: read, write, list, or delete"
@@ -55,7 +93,7 @@ function createMemory(config = {}) {
             return `Error [memory]: Unknown action "${String(action)}".`;
         }
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = extractErrorMessage(error);
         return `Error [memory]: ${msg}`;
       }
     }
@@ -65,20 +103,19 @@ async function writeEntry(dir, key, content) {
   if (!content && content !== "") {
     return "Error [memory]: Content is required for write action.";
   }
-  await mkdir(dir, { recursive: true });
-  await writeFile(join(dir, `${key}.md`), content, "utf-8");
+  await writeTextContent(join(dir, `${key}.md`), content);
   return `Saved memory "${key}".`;
 }
 async function readEntry(dir, key) {
   try {
-    return await readFile(join(dir, `${key}.md`), "utf-8");
+    return await readTextContent(join(dir, `${key}.md`));
   } catch {
     return `Error [memory]: Key "${key}" not found.`;
   }
 }
 async function listKeys(dir) {
   try {
-    const files = await readdir(dir);
+    const files = await listDirectory(dir);
     const keys = files.filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -3));
     if (keys.length === 0) return "No memory entries found.";
     return keys.join("\n");
@@ -88,7 +125,7 @@ async function listKeys(dir) {
 }
 async function deleteEntry(dir, key) {
   try {
-    await unlink(join(dir, `${key}.md`));
+    await removeFile(join(dir, `${key}.md`));
     return `Deleted memory "${key}".`;
   } catch {
     return `Error [memory]: Key "${key}" not found.`;
@@ -97,6 +134,7 @@ async function deleteEntry(dir, key) {
 var memory = createMemory();
 
 export {
+  getPrompt,
   createMemory,
   memory
 };

package/dist/{chunk-G3ITTPGX.js → chunk-4MXDQEPA.js}

@@ -47,6 +47,16 @@ function applyEditToFile(originalContent, oldString, newString, replaceAll = fal
   const stripTrailingNewline = !oldString.endsWith("\n") && originalContent.includes(oldString + "\n");
   return stripTrailingNewline ? f(originalContent, oldString + "\n", newString) : f(originalContent, oldString, newString);
 }
+function countOccurrences(text, search) {
+  if (search.length === 0) return 0;
+  let count = 0;
+  let pos = 0;
+  while ((pos = text.indexOf(search, pos)) !== -1) {
+    count++;
+    pos += search.length;
+  }
+  return count;
+}
 function isOpeningContext(chars, index) {
   if (index === 0) {
     return true;
@@ -95,5 +105,6 @@ function applyCurlySingleQuotes(str) {
 export {
   findActualString,
   preserveQuoteStyle,
-  applyEditToFile
+  applyEditToFile,
+  countOccurrences
 };

package/dist/{chunk-CGTPF6IS.js → chunk-4UUSERSH.js}

@@ -1,14 +1,18 @@
+import {
+  readTextContent
+} from "./chunk-PWBVB6MN.js";
 import {
   expandPath
 } from "./chunk-I3ONDY7P.js";
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
 
 // src/diff/index.ts
-import { readFile as readFile2 } from "fs/promises";
 import { tool } from "ai";
 import { z } from "zod";
 
 // src/shared/diff.ts
-import { readFile } from "fs/promises";
 import { createTwoFilesPatch } from "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([
-    readFile(oldFilePath, "utf-8"),
-    readFile(newFilePath, "utf-8")
+    readTextContent(oldFilePath),
+    readTextContent(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 = config.cwd ?? process.cwd();
   return tool({
-    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: config.description ?? getPrompt(),
     inputSchema: z.object({
       file_path: z.string().optional().describe("Path to the first file (absolute or relative to cwd)"),
       other_file_path: 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 = expandPath(file_path, cwd);
-          const fileContent = await readFile2(resolvedPath, "utf-8");
+          const fileContent = await readTextContent(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 = extractErrorMessage(error);
         return `Error [diff]: ${msg}`;
       }
     }
@@ -85,6 +108,7 @@ function createDiff(config = {}) {
 var diff = createDiff();
 
 export {
+  getPrompt,
   createDiff,
   diff
 };