agentool 1.0.0 → 1.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 # agentool
 
-**16 AI agent tools as standalone [Vercel AI SDK](https://sdk.vercel.ai/) modules.**
+**22 AI agent tools as standalone [Vercel AI SDK](https://sdk.vercel.ai/) modules.**
 
   <p>
   <a href="https://www.npmjs.com/package/agentool"><img src="https://img.shields.io/npm/v/agentool?style=flat-square&color=cb3837&logo=npm" alt="npm version" /></a>
@@ -27,13 +27,13 @@ File operations, shell execution, code search, web fetching, and more -- everyth
 
 ## Features
 
-- **16 production-ready tools** -- bash, grep, glob, read, edit, write, web-fetch, memory, multi-edit, diff, task, lsp, http-request, context-compaction, ask-user, sleep
+- **22 production-ready tools** -- bash, grep, glob, read, edit, write, web-fetch, web-search, tool-search, memory, multi-edit, diff, task-create, task-get, task-update, task-list, lsp, http-request, context-compaction, ask-user, sleep
 - **Vercel AI SDK compatible** -- works with `generateText()`, `streamText()`, and any AI SDK provider (OpenAI, Anthropic, Google, etc.)
 - **Factory + default pattern** -- `createBash({ cwd: '/my/project' })` for custom config, or just use `bash` with zero config
 - **Dual ESM/CJS** -- works everywhere with proper `exports` map
 - **TypeScript-first** -- full type declarations, strict mode, no `any`
 - **Never throws** -- every `execute()` returns a descriptive error string instead of throwing
-- **Tree-shakeable** -- 17 subpath exports, only import what you need
+- **Tree-shakeable** -- 22 subpath exports, only import what you need
 
 ## Installation
 
@@ -326,7 +326,58 @@ const result = await webFetch.execute(
 // Returns markdown content (HTML converted via Turndown, truncated at 100K chars)
 ```
 
-**Parameters:** `url` (string), `prompt?` (string)
+**Parameters:** `url` (string, must be valid URL)
+
+---
+
+### web-search
+
+Search the web with a callback-based implementation (bring your own search provider).
+
+```typescript
+import { createWebSearch } from 'agentool/web-search';
+
+const webSearch = createWebSearch({
+  onSearch: async (query, { allowed_domains, blocked_domains }) => {
+    // Use Tavily, SerpAPI, Google, or any search provider
+    const results = await mySearchProvider.search(query, { allowed_domains, blocked_domains });
+    return results.map(r => `${r.title}: ${r.url}\n${r.snippet}`).join('\n\n');
+  },
+});
+
+const result = await webSearch.execute(
+  { query: 'TypeScript best practices 2024', allowed_domains: ['typescript-eslint.io'] },
+  { toolCallId: 'id', messages: [] },
+);
+```
+
+**Parameters:** `query` (string, min 2 chars), `allowed_domains?` (string[]), `blocked_domains?` (string[])
+
+---
+
+### tool-search
+
+Search through a registry of available tools by name or keyword.
+
+```typescript
+import { createToolSearch } from 'agentool/tool-search';
+
+const toolSearch = createToolSearch({
+  tools: {
+    bash: { description: 'Execute shell commands' },
+    grep: { description: 'Search file contents with regex' },
+    read: { description: 'Read file contents' },
+  },
+});
+
+const result = await toolSearch.execute(
+  { query: 'file', max_results: 3 },
+  { toolCallId: 'id', messages: [] },
+);
+// Returns matching tools sorted by relevance
+```
+
+**Parameters:** `query` (string), `max_results?` (number, default 5)
 
 ---
 
@@ -390,33 +441,78 @@ await memory.execute(
 
 ---
 
-### task
+### task-create
 
-JSON file-based task tracker for agent workflows.
+Create a new task with subject, description, and optional metadata.
 
 ```typescript
-import { task } from 'agentool/task';
+import { taskCreate } from 'agentool/task-create';
 
-// Create
-const created = await task.execute(
-  { action: 'create', subject: 'Fix login bug', description: 'Auth fails on refresh' },
+const result = await taskCreate.execute(
+  { subject: 'Fix login bug', description: 'Auth fails on refresh', metadata: { priority: 'high' } },
   { toolCallId: 'id', messages: [] },
 );
+```
 
-// List all
-const list = await task.execute(
-  { action: 'list' },
+**Parameters:** `subject` (string), `description` (string), `metadata?` (Record<string, unknown>)
+
+---
+
+### task-get
+
+Retrieve a task by ID to see full details.
+
+```typescript
+import { taskGet } from 'agentool/task-get';
+
+const result = await taskGet.execute(
+  { taskId: 'abc123' },
   { toolCallId: 'id', messages: [] },
 );
+```
+
+**Parameters:** `taskId` (string)
+
+---
+
+### task-update
+
+Update a task's status, owner, metadata, and dependency relationships.
+
+```typescript
+import { taskUpdate } from 'agentool/task-update';
+
+// Update status and owner
+await taskUpdate.execute(
+  { taskId: 'abc123', status: 'in_progress', owner: 'agent-1' },
+  { toolCallId: 'id', messages: [] },
+);
+
+// Add dependencies and merge metadata (null deletes a key)
+await taskUpdate.execute(
+  { taskId: 'abc123', addBlockedBy: ['def456'], metadata: { priority: null, notes: 'reviewed' } },
+  { toolCallId: 'id', messages: [] },
+);
+```
+
+**Parameters:** `taskId` (string), `subject?` (string), `description?` (string), `status?` (`'pending'` | `'in_progress'` | `'completed'` | `'deleted'`), `owner?` (string), `activeForm?` (string), `addBlocks?` (string[]), `addBlockedBy?` (string[]), `metadata?` (Record<string, unknown>)
+
+---
+
+### task-list
+
+List all non-deleted tasks with status and dependencies.
+
+```typescript
+import { taskList } from 'agentool/task-list';
 
-// Update status
-await task.execute(
-  { action: 'update', id: 'abc123', status: 'completed' },
+const result = await taskList.execute(
+  {},
   { toolCallId: 'id', messages: [] },
 );
 ```
 
-**Parameters:** `action` (`'create'` | `'get'` | `'update'` | `'list'` | `'delete'`), `id?` (string), `subject?` (string), `description?` (string), `status?` (`'pending'` | `'in_progress'` | `'completed'`)
+**Parameters:** none
 
 ---
 
@@ -440,7 +536,7 @@ const result = await lsp.execute(
 );
 ```
 
-**Parameters:** `operation` (`'goToDefinition'` | `'findReferences'` | `'hover'` | `'documentSymbol'` | `'workspaceSymbol'` | `'goToImplementation'` | `'incomingCalls'` | `'outgoingCalls'`), `filePath` (string), `line?` (number), `character?` (number), `query?` (string)
+**Parameters:** `operation` (`'goToDefinition'` | `'findReferences'` | `'hover'` | `'documentSymbol'` | `'workspaceSymbol'` | `'goToImplementation'` | `'prepareCallHierarchy'` | `'incomingCalls'` | `'outgoingCalls'`), `filePath` (string), `line` (number, 1-based), `character` (number, 1-based)
 
 ---
 
@@ -552,7 +648,12 @@ Tools that support timeouts extend `TimeoutConfig`:
 | `bash` | `shell?: string` -- shell binary path |
 | `read` | `maxLines?: number` -- max lines to return (default: 2000) |
 | `memory` | `memoryDir?: string` -- storage directory |
-| `task` | `tasksFile?: string` -- JSON file path |
+| `task-create` | `tasksFile?: string` -- JSON file path |
+| `task-get` | `tasksFile?: string` -- JSON file path |
+| `task-update` | `tasksFile?: string` -- JSON file path |
+| `task-list` | `tasksFile?: string` -- JSON file path |
+| `web-search` | `onSearch?: (query, opts) => Promise<string>` -- search callback |
+| `tool-search` | `tools?: Record<string, { description }>` -- tool registry |
 | `lsp` | `servers?: Record<string, LspServerConfig>` -- LSP servers by file extension |
 | `http-request` | `defaultHeaders?: Record<string, string>` -- headers merged into every request |
 | `web-fetch` | `maxContentLength?: number`, `userAgent?: string` |
@@ -587,11 +688,16 @@ import {
   grep, createGrep,
   glob, createGlob,
   webFetch, createWebFetch,
+  webSearch, createWebSearch,
+  toolSearch, createToolSearch,
   httpRequest, createHttpRequest,
   memory, createMemory,
   multiEdit, createMultiEdit,
   diff, createDiff,
-  task, createTask,
+  taskCreate, createTaskCreate,
+  taskGet, createTaskGet,
+  taskUpdate, createTaskUpdate,
+  taskList, createTaskList,
   lsp, createLsp,
   contextCompaction, createContextCompaction,
   askUser, createAskUser,
@@ -613,7 +719,12 @@ import { httpRequest } from 'agentool/http-request';
 import { memory } from 'agentool/memory';
 import { multiEdit } from 'agentool/multi-edit';
 import { diff } from 'agentool/diff';
-import { task } from 'agentool/task';
+import { taskCreate } from 'agentool/task-create';
+import { taskGet } from 'agentool/task-get';
+import { taskUpdate } from 'agentool/task-update';
+import { taskList } from 'agentool/task-list';
+import { webSearch } from 'agentool/web-search';
+import { toolSearch } from 'agentool/tool-search';
 import { lsp } from 'agentool/lsp';
 import { contextCompaction } from 'agentool/context-compaction';
 import { askUser } from 'agentool/ask-user';

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-2JBLVFB7.cjs

@@ -0,0 +1,74 @@
+"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: _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")
+    }),
+    execute: async ({ query, max_results }) => {
+      try {
+        const registry = _nullishCoalesce(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 = _chunkKONXT2SFcjs.extractErrorMessage.call(void 0, error);
+        return `Error [tool-search]: ${msg}`;
+      }
+    }
+  });
+}
+var toolSearch = createToolSearch();
+
+
+
+
+
+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-XKG2A3EW.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,22 +83,22 @@ 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("Regex pattern to search for"),
-      path: z.string().optional().describe("File or directory to search in"),
-      glob: z.string().optional().describe('Glob pattern to filter files (e.g. "*.js")'),
-      output_mode: z.enum(["content", "files_with_matches", "count"]).optional().describe('Output mode. Defaults to "files_with_matches".'),
-      "-B": z.number().optional().describe("Lines of context before each match"),
-      "-A": z.number().optional().describe("Lines of context after each match"),
-      "-C": z.number().optional().describe("Lines of context around each match"),
-      context: z.number().optional().describe("Context lines (alias for -C)"),
-      "-n": z.boolean().optional().describe("Show line numbers (content mode, default true)"),
-      "-i": z.boolean().optional().describe("Case insensitive search"),
-      type: z.string().optional().describe('File type filter (e.g. "js", "py")'),
-      head_limit: z.number().optional().describe("Max entries. Default 250, 0 = unlimited."),
-      offset: z.number().optional().describe("Skip first N entries. Default 0."),
-      multiline: z.boolean().optional().describe("Enable multiline matching")
+      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."),
+      glob: z.string().optional().describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}") - maps to rg --glob'),
+      output_mode: z.enum(["content", "files_with_matches", "count"]).optional().describe('Output mode: "content" shows matching lines (supports -A/-B/-C context, -n line numbers, head_limit), "files_with_matches" shows file paths (supports head_limit), "count" shows match counts (supports head_limit). Defaults to "files_with_matches".'),
+      "-B": z.number().optional().describe('Number of lines to show before each match (rg -B). Requires output_mode: "content", ignored otherwise.'),
+      "-A": z.number().optional().describe('Number of lines to show after each match (rg -A). Requires output_mode: "content", ignored otherwise.'),
+      "-C": z.number().optional().describe("Alias for context."),
+      context: z.number().optional().describe('Number of lines to show before and after each match (rg -C). Requires output_mode: "content", ignored otherwise.'),
+      "-n": z.boolean().optional().describe('Show line numbers in output (rg -n). Requires output_mode: "content", ignored otherwise. Defaults to true.'),
+      "-i": z.boolean().optional().describe("Case insensitive search (rg -i)"),
+      type: z.string().optional().describe("File type to search (rg --type). Common types: js, py, rust, go, java, etc. More efficient than include for standard file types."),
+      head_limit: z.number().optional().describe('Limit output to first N lines/entries, equivalent to "| head -N". Works across all output modes: content (limits output lines), files_with_matches (limits file paths), count (limits count entries). Defaults to 250 when unspecified. Pass 0 for unlimited (use sparingly \u2014 large result sets waste context).'),
+      offset: z.number().optional().describe('Skip first N lines/entries before applying head_limit, equivalent to "| tail -n +N | head -N". Works across all output modes. Defaults to 0.'),
+      multiline: z.boolean().optional().describe("Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall). Default: false.")
     }),
     execute: async (input) => {
       try {
@@ -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
 };