agentool 1.0.0 → 1.1.1

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-T6STO7PS.cjs

@@ -0,0 +1,126 @@
+"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-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: _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"),
+      description: _zod.z.string().optional().describe("New description"),
+      status: _zod.z.enum(["pending", "in_progress", "completed", "deleted"]).optional().describe("New status for the task"),
+      owner: _zod.z.string().optional().describe("New owner for the task"),
+      activeForm: _zod.z.string().optional().describe("Present continuous form shown in spinner when in_progress"),
+      addBlocks: _zod.z.array(_zod.z.string()).optional().describe("Task IDs that this task blocks"),
+      addBlockedBy: _zod.z.array(_zod.z.string()).optional().describe("Task IDs that block this task"),
+      metadata: _zod.z.record(_zod.z.string(), _zod.z.unknown()).optional().describe("Metadata keys to merge. Set key to null to delete.")
+    }),
+    execute: async (input) => {
+      try {
+        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];
+        if (input.subject !== void 0) entry.subject = input.subject;
+        if (input.description !== void 0) entry.description = input.description;
+        if (input.status !== void 0) entry.status = input.status;
+        if (input.owner !== void 0) entry.owner = input.owner;
+        if (input.activeForm !== void 0) entry.activeForm = input.activeForm;
+        if (input.addBlocks) {
+          for (const id of input.addBlocks) {
+            if (!entry.blocks.includes(id)) entry.blocks.push(id);
+          }
+        }
+        if (input.addBlockedBy) {
+          for (const id of input.addBlockedBy) {
+            if (!entry.blockedBy.includes(id)) entry.blockedBy.push(id);
+          }
+        }
+        if (input.metadata) {
+          if (!entry.metadata) entry.metadata = {};
+          for (const [key, value] of Object.entries(input.metadata)) {
+            if (value === null) {
+              delete entry.metadata[key];
+            } else {
+              entry.metadata[key] = value;
+            }
+          }
+        }
+        entry.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+        tasks[idx] = entry;
+        await _chunkVQSWMGG7cjs.saveTasks.call(void 0, tasksFile, tasks);
+        return `Updated task ${input.taskId}.
+${_chunkVQSWMGG7cjs.formatTask.call(void 0, entry)}`;
+      } catch (error) {
+        const msg = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
+        return `Error [task-update]: ${msg}`;
+      }
+    }
+  });
+}
+var taskUpdate = createTaskUpdate();
+
+
+
+
+
+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-TM5L4HA5.js

@@ -0,0 +1,126 @@
+import {
+  formatTask,
+  loadTasks,
+  saveTasks
+} 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: 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"),
+      description: z.string().optional().describe("New description"),
+      status: z.enum(["pending", "in_progress", "completed", "deleted"]).optional().describe("New status for the task"),
+      owner: z.string().optional().describe("New owner for the task"),
+      activeForm: z.string().optional().describe("Present continuous form shown in spinner when in_progress"),
+      addBlocks: z.array(z.string()).optional().describe("Task IDs that this task blocks"),
+      addBlockedBy: z.array(z.string()).optional().describe("Task IDs that block this task"),
+      metadata: z.record(z.string(), z.unknown()).optional().describe("Metadata keys to merge. Set key to null to delete.")
+    }),
+    execute: async (input) => {
+      try {
+        const tasks = await loadTasks(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];
+        if (input.subject !== void 0) entry.subject = input.subject;
+        if (input.description !== void 0) entry.description = input.description;
+        if (input.status !== void 0) entry.status = input.status;
+        if (input.owner !== void 0) entry.owner = input.owner;
+        if (input.activeForm !== void 0) entry.activeForm = input.activeForm;
+        if (input.addBlocks) {
+          for (const id of input.addBlocks) {
+            if (!entry.blocks.includes(id)) entry.blocks.push(id);
+          }
+        }
+        if (input.addBlockedBy) {
+          for (const id of input.addBlockedBy) {
+            if (!entry.blockedBy.includes(id)) entry.blockedBy.push(id);
+          }
+        }
+        if (input.metadata) {
+          if (!entry.metadata) entry.metadata = {};
+          for (const [key, value] of Object.entries(input.metadata)) {
+            if (value === null) {
+              delete entry.metadata[key];
+            } else {
+              entry.metadata[key] = value;
+            }
+          }
+        }
+        entry.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+        tasks[idx] = entry;
+        await saveTasks(tasksFile, tasks);
+        return `Updated task ${input.taskId}.
+${formatTask(entry)}`;
+      } catch (error) {
+        const msg = extractErrorMessage(error);
+        return `Error [task-update]: ${msg}`;
+      }
+    }
+  });
+}
+var taskUpdate = createTaskUpdate();
+
+export {
+  getPrompt,
+  createTaskUpdate,
+  taskUpdate
+};

package/dist/{chunk-4YI2H55A.js → chunk-TXZ3BMMR.js}

@@ -1,3 +1,7 @@
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
+
 // src/bash/index.ts
 import { tool } from "ai";
 import { z } from "zod";
@@ -103,12 +107,54 @@ async function executeShell(command, options) {
   });
 }
 
+// src/bash/prompt.ts
+function getPrompt(config = {}) {
+  const timeout = config.timeout ?? 12e4;
+  const timeoutMin = timeout / 6e4;
+  const shell = config.shell ?? "$SHELL or /bin/bash";
+  return `Execute a shell command and return its output (stdout, stderr, exit code).
+
+Runs the command in ${shell} with \`-c\`. The working directory persists between calls.
+
+## When to Use
+- Build commands, git operations, system administration, installing packages
+- Running scripts, compiling code, process management
+- Any shell task that doesn't have a dedicated tool available
+
+## When NOT to Use
+- Reading file contents \u2014 use the dedicated file reading tool instead
+- Searching file contents \u2014 use the dedicated content search tool instead
+- Finding files by name/pattern \u2014 use the dedicated file search tool instead
+- Editing files \u2014 use the dedicated file editing tool instead
+- Writing new files \u2014 use the dedicated file writing tool instead
+Prefer dedicated tools over shell equivalents (e.g., don't use cat, head, tail, sed, awk, grep, find, or echo when a dedicated tool exists). Dedicated tools provide better output formatting and permission handling.
+
+## Usage Guidelines
+- Default timeout: ${timeout}ms (${timeoutMin} minutes). Override with the timeout parameter.
+- Timeout escalation: SIGTERM first, then SIGKILL after 5-second grace period.
+- Output is capped at 10 MB per stream (stdout/stderr).
+- Always quote file paths containing spaces with double quotes.
+- When issuing multiple commands:
+  - Independent commands: make separate tool calls in parallel.
+  - Sequential with dependency: chain with \`&&\`.
+  - Sequential ignoring failures: chain with \`;\`.
+  - Do NOT use newlines to separate commands.
+- Avoid unnecessary \`sleep\` commands:
+  - Don't sleep between commands that can run immediately.
+  - Don't retry failing commands in a sleep loop \u2014 diagnose the root cause.
+  - If you must sleep, keep it short (1-5 seconds).
+- For git commands:
+  - Prefer creating new commits rather than amending existing ones.
+  - Never skip hooks (--no-verify) unless the user explicitly requests it.
+  - Before destructive operations (reset --hard, push --force), consider safer alternatives.`;
+}
+
 // src/bash/index.ts
 function createBash(config = {}) {
   const cwd = config.cwd ?? process.cwd();
   const timeout = config.timeout ?? 12e4;
   return tool({
-    description: "Execute a shell command and return its output. Runs the command in a bash shell with the configured working directory. Returns stdout, stderr, and exit code. Use this for running build commands, git operations, system administration, and any other shell tasks.",
+    description: config.description ?? getPrompt(config),
     inputSchema: z.object({
       command: z.string().describe("The shell command to execute"),
       timeout: z.number().optional().describe("Timeout in milliseconds (default: 120000)"),
@@ -128,7 +174,7 @@ ${result.stderr}`);
         if (result.exitCode !== 0) parts.push(`Exit code: ${result.exitCode}`);
         return parts.length > 0 ? parts.join("\n") : `Command completed with exit code ${result.exitCode}`;
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = extractErrorMessage(error);
         return `Error [bash]: Failed to execute command: ${msg}`;
       }
     }
@@ -137,6 +183,7 @@ ${result.stderr}`);
 var bash = createBash();
 
 export {
+  getPrompt,
   createBash,
   bash
 };

package/dist/chunk-UCA6LURO.js

@@ -0,0 +1,74 @@
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
+
+// src/tool-search/index.ts
+import { tool } from "ai";
+import { z } from "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 tool({
+    description: config.description ?? getPrompt(),
+    inputSchema: z.object({
+      query: z.string().describe("Query to find tools by name or keyword"),
+      max_results: z.number().optional().default(5).describe("Max results to return")
+    }),
+    execute: async ({ query, max_results }) => {
+      try {
+        const registry = config.tools ?? {};
+        const entries = Object.entries(registry);
+        if (entries.length === 0) {
+          return "No tools registered. Provide a tools registry via createToolSearch({ tools: { ... } })";
+        }
+        const lower = query.toLowerCase();
+        const scored = entries.map(([name, { description }]) => {
+          let score = 0;
+          const nameLower = name.toLowerCase();
+          const descLower = description.toLowerCase();
+          if (nameLower === lower) score += 10;
+          else if (nameLower.includes(lower)) score += 5;
+          if (descLower.includes(lower)) score += 3;
+          for (const word of lower.split(/\s+/)) {
+            if (nameLower.includes(word)) score += 2;
+            if (descLower.includes(word)) score += 1;
+          }
+          return { name, description, score };
+        }).filter((e) => e.score > 0).sort((a, b) => b.score - a.score).slice(0, max_results);
+        if (scored.length === 0) {
+          return `No tools matched query "${query}".`;
+        }
+        return scored.map((e) => `${e.name}: ${e.description}`).join("\n");
+      } catch (error) {
+        const msg = extractErrorMessage(error);
+        return `Error [tool-search]: ${msg}`;
+      }
+    }
+  });
+}
+var toolSearch = createToolSearch();
+
+export {
+  getPrompt,
+  createToolSearch,
+  toolSearch
+};

package/dist/{chunk-EA3YV7ZG.js → chunk-VE4U27HI.js}

@@ -1,33 +1,52 @@
 import {
   applyEditToFile,
+  countOccurrences,
   findActualString,
   preserveQuoteStyle
-} from "./chunk-G3ITTPGX.js";
+} from "./chunk-4MXDQEPA.js";
 import {
+  readTextContent,
   writeTextContent
-} from "./chunk-6PQLFDGT.js";
+} from "./chunk-PWBVB6MN.js";
 import {
   expandPath
 } from "./chunk-I3ONDY7P.js";
+import {
+  extractErrorMessage
+} from "./chunk-X6ZY2KFU.js";
 
 // src/multi-edit/index.ts
-import { readFile } from "fs/promises";
 import { tool } from "ai";
 import { z } from "zod";
-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;
+
+// src/multi-edit/prompt.ts
+function getPrompt() {
+  return `Atomically apply multiple text edits to a single file. All edits succeed together or none are applied.
+
+Each edit replaces one occurrence of old_string with new_string. Edits are applied sequentially in the order provided.
+
+## When to Use
+- When you need to make several related changes to the same file in one operation
+- When changes depend on each other and partial application would leave the file in a broken state
+- To rename a variable in multiple locations within the same file
+
+## When NOT to Use
+- For a single edit \u2014 use the regular file editing tool instead (simpler)
+- For changes across multiple files \u2014 make separate edit calls per file
+- For creating new files \u2014 use the file writing tool instead
+
+## Usage Guidelines
+- If any edit fails (old_string not found or not unique), the entire batch is rolled back \u2014 the file stays unchanged
+- Each old_string must appear exactly once in the file at the time that edit is applied
+- Edits are applied in order, so later edits see the result of earlier ones
+- Supports curly-quote fallback matching and quote-style preservation`;
 }
+
+// src/multi-edit/index.ts
 function createMultiEdit(config = {}) {
   const cwd = config.cwd ?? process.cwd();
   return tool({
-    description: "Atomically apply multiple text edits to a single file. All edits succeed together or none are applied (rollback on failure). Each edit replaces one occurrence of old_string with new_string. Edits are applied sequentially in the order provided.",
+    description: config.description ?? getPrompt(),
     inputSchema: z.object({
       file_path: z.string().describe("Path to the file to edit (absolute or relative to cwd)"),
       edits: z.array(
@@ -43,7 +62,7 @@ function createMultiEdit(config = {}) {
           return "No edits provided. File unchanged.";
         }
         const resolvedPath = expandPath(file_path, cwd);
-        const originalContent = await readFile(resolvedPath, "utf-8");
+        const originalContent = await readTextContent(resolvedPath);
         let content = originalContent;
         for (let i = 0; i < edits.length; i++) {
           const edit = edits[i];
@@ -65,7 +84,7 @@ function createMultiEdit(config = {}) {
         await writeTextContent(resolvedPath, content);
         return `Successfully applied ${edits.length} edit${edits.length === 1 ? "" : "s"} to ${resolvedPath}`;
       } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
+        const msg = extractErrorMessage(error);
         return `Error [multi-edit]: ${msg}`;
       }
     }
@@ -74,6 +93,7 @@ function createMultiEdit(config = {}) {
 var multiEdit = createMultiEdit();
 
 export {
+  getPrompt,
   createMultiEdit,
   multiEdit
 };