token-pilot 0.15.0 → 0.16.1

package/dist/handlers/read-symbols.js

@@ -0,0 +1,142 @@
+import { readFile } from 'node:fs/promises';
+import { estimateTokens } from '../core/token-estimator.js';
+import { resolveSafePath } from '../core/validation.js';
+import { assessConfidence, formatConfidence } from '../core/confidence.js';
+export async function handleReadSymbols(args, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, advisoryReminders = true) {
+    const absPath = resolveSafePath(projectRoot, args.path);
+    // Get file content ONCE
+    const cached = fileCache.get(absPath);
+    let lines;
+    if (cached) {
+        lines = cached.lines;
+    }
+    else {
+        const content = await readFile(absPath, 'utf-8');
+        lines = content.split('\n');
+    }
+    // Get AST structure ONCE
+    let structure = cached?.structure;
+    if (!structure && astIndex) {
+        structure = await astIndex.outline(absPath) ?? undefined;
+    }
+    const N = args.symbols.length;
+    const sections = [];
+    // Show mode constants (same as read_symbol.ts)
+    const MAX_SYMBOL_LINES = 300;
+    const MAX_FULL_LINES = 500;
+    const HEAD = 50;
+    const TAIL = 30;
+    let anyTruncated = false;
+    let anyResolved = false;
+    let totalTokens = 0;
+    for (let i = 0; i < N; i++) {
+        const symbolName = args.symbols[i];
+        const idx = i + 1;
+        const resolved = await symbolResolver.resolve(symbolName, structure);
+        if (!resolved) {
+            sections.push(`SYMBOL ${idx}/${N}: ${symbolName}\n` +
+                `ERROR: Symbol "${symbolName}" not found in ${args.path}.\n` +
+                `HINT: Use smart_read("${args.path}") to see available symbols.`);
+            continue;
+        }
+        anyResolved = true;
+        const source = symbolResolver.extractSource(resolved, lines, {
+            contextBefore: args.context_before ?? 2,
+            contextAfter: args.context_after ?? 0,
+        });
+        const loc = `[L${resolved.startLine}-${resolved.endLine}]`;
+        const lineCount = resolved.endLine - resolved.startLine + 1;
+        // Determine effective show mode
+        const showMode = args.show ?? (lineCount > MAX_SYMBOL_LINES ? 'outline' : 'full');
+        let displaySource = source;
+        let truncated = false;
+        if (showMode === 'full') {
+            if (lineCount > MAX_FULL_LINES) {
+                const sourceLines = source.split('\n');
+                displaySource = sourceLines.slice(0, MAX_FULL_LINES).join('\n');
+                displaySource += `\n\n    ... truncated at ${MAX_FULL_LINES} lines (${lineCount - MAX_FULL_LINES} more). Use show="head"/"tail" for targeted view.`;
+                truncated = true;
+            }
+        }
+        else if (showMode === 'head') {
+            const sourceLines = source.split('\n');
+            displaySource = sourceLines.slice(0, HEAD).join('\n');
+            if (lineCount > HEAD) {
+                displaySource += `\n\n    ... ${lineCount - HEAD} more lines. Use show="tail" or read_symbol("${args.path}", "MethodName") for specific parts.`;
+                truncated = true;
+            }
+        }
+        else if (showMode === 'tail') {
+            const sourceLines = source.split('\n');
+            displaySource = sourceLines.slice(-TAIL).join('\n');
+            if (lineCount > TAIL) {
+                displaySource = `    ... ${lineCount - TAIL} lines above ...\n\n` + displaySource;
+                truncated = true;
+            }
+        }
+        else {
+            // 'outline' mode: head + method list + tail
+            if (lineCount > HEAD + TAIL) {
+                const sourceLines = source.split('\n');
+                const head = sourceLines.slice(0, HEAD).join('\n');
+                const tail = sourceLines.slice(-TAIL).join('\n');
+                const omitted = sourceLines.length - HEAD - TAIL;
+                let methodOutline = '';
+                if (resolved.symbol.children && resolved.symbol.children.length > 0) {
+                    const methodLines = resolved.symbol.children.map(c => {
+                        const mLoc = `[L${c.location.startLine}-${c.location.endLine}]`;
+                        return `  ${c.visibility === 'private' ? '🔒 ' : ''}${c.name}${c.kind === 'method' || c.kind === 'function' ? '()' : ''} ${mLoc} (${c.location.lineCount} lines)`;
+                    });
+                    methodOutline = `\nMETHODS (${resolved.symbol.children.length}):\n${methodLines.join('\n')}\n`;
+                }
+                displaySource = [
+                    head,
+                    '',
+                    `    ... ${omitted} lines omitted — use read_symbol("${args.path}", "MethodName") to read specific methods ...`,
+                    methodOutline,
+                    tail,
+                ].join('\n');
+                truncated = true;
+            }
+        }
+        if (truncated)
+            anyTruncated = true;
+        const symbolLines = [
+            `SYMBOL ${idx}/${N}: ${symbolName} (${resolved.symbol.kind}) ${loc} (${lineCount} lines${truncated ? `, show=${showMode}` : ''})`,
+            '',
+            displaySource,
+        ];
+        if (resolved.symbol.references.length > 0) {
+            symbolLines.push('');
+            symbolLines.push(`REFERENCES: ${resolved.symbol.references.join(', ')}`);
+        }
+        sections.push(symbolLines.join('\n'));
+        // Track each symbol
+        const sectionTokens = estimateTokens(symbolLines.join('\n'));
+        totalTokens += sectionTokens;
+        contextRegistry.trackLoad(absPath, {
+            type: 'symbol',
+            symbolName,
+            startLine: resolved.startLine,
+            endLine: resolved.endLine,
+            tokens: sectionTokens,
+        });
+    }
+    if (cached?.hash) {
+        contextRegistry.setContentHash(absPath, cached.hash);
+    }
+    const header = `FILE: ${args.path} | SYMBOLS: ${N} requested`;
+    const body = sections.join('\n\n---\n\n');
+    const footer = 'CONTEXT TRACKED: These symbols are now in your context.';
+    const output = [header, '', body, '', footer].join('\n');
+    // Confidence metadata (aggregate)
+    const confidenceMeta = assessConfidence({
+        symbolResolved: anyResolved,
+        truncated: anyTruncated,
+        fullFile: false,
+        hasCallers: false,
+        astAvailable: !!structure,
+    });
+    return { content: [{ type: 'text', text: output + formatConfidence(confidenceMeta) }] };
+}
+//# sourceMappingURL=read-symbols.js.map

package/dist/handlers/smart-diff.js

@@ -221,6 +221,29 @@ function formatSmartDiff(allFiles, processedFiles, symbolChanges, args, rawToken
     const lines = [];
     lines.push(`CHANGES: ${allFiles.length} file${allFiles.length !== 1 ? 's' : ''}, +${totalAdded} -${totalRemoved} (${scopeLabel})`);
     lines.push('');
+    // Affected symbols summary
+    const allSymbolChanges = [];
+    for (const [file, changes] of symbolChanges) {
+        for (const sc of changes) {
+            allSymbolChanges.push({ file, symbol: sc });
+        }
+    }
+    if (allSymbolChanges.length > 0) {
+        lines.push('AFFECTED SYMBOLS:');
+        // Group by changeType
+        const modified = allSymbolChanges.filter(s => s.symbol.changeType === 'MODIFIED');
+        const added = allSymbolChanges.filter(s => s.symbol.changeType === 'ADDED');
+        const removed = allSymbolChanges.filter(s => s.symbol.changeType === 'REMOVED');
+        for (const [label, group] of [['MODIFIED', modified], ['ADDED', added], ['REMOVED', removed]]) {
+            if (group.length === 0)
+                continue;
+            for (const item of group) {
+                const parens = ['function', 'method'].includes(item.symbol.kind) ? '()' : '';
+                lines.push(`  ${label}: ${item.file}::${item.symbol.name}${parens}`);
+            }
+        }
+        lines.push('');
+    }
     for (const fd of processedFiles) {
         if (lines.length >= MAX_OUTPUT_LINES) {
             lines.push(`... truncated (${allFiles.length - processedFiles.indexOf(fd)} more files)`);

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { readFileSync, realpathSync } from 'node:fs';
+import { readFileSync, realpathSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
@@ -171,9 +172,10 @@ export function handleHookRead(filePathArg, denyThreshold = 300) {
     }
     // Check file size
     let lineCount = 0;
+    let fileContent = '';
     try {
-        const content = readFileSync(filePath, 'utf-8');
-        lineCount = content.split('\n').length;
+        fileContent = readFileSync(filePath, 'utf-8');
+        lineCount = fileContent.split('\n').length;
         if (lineCount <= denyThreshold) {
             process.exit(0);
         }
@@ -181,6 +183,19 @@ export function handleHookRead(filePathArg, denyThreshold = 300) {
     catch {
         process.exit(0);
     }
+    // Track denied read for session analytics
+    try {
+        const charEst = Math.ceil(fileContent.length / 4);
+        const wsRatio = (fileContent.match(/\s/g)?.length ?? 0) / fileContent.length;
+        const estTokens = Math.ceil(charEst * (1 - wsRatio * 0.3));
+        const entry = JSON.stringify({ filePath, lineCount, estimatedTokens: estTokens, timestamp: Date.now() });
+        const dir = join(process.cwd(), '.token-pilot');
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(join(dir, 'hook-denied.jsonl'), entry + '\n');
+    }
+    catch {
+        // Silent fail — hook must not break
+    }
     // Large code file, unbounded Read → DENY
     // permissionDecisionReason is shown to Claude (not user) per official docs
     const deny = JSON.stringify({

package/dist/server/tool-definitions.d.ts

@@ -29,6 +29,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -45,6 +46,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -88,6 +90,7 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -104,6 +107,71 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
+            module?: undefined;
+            export_only?: undefined;
+            check?: undefined;
+            pattern?: undefined;
+            name?: undefined;
+            ref?: undefined;
+            count?: undefined;
+            command?: undefined;
+            runner?: undefined;
+            timeout?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            symbols: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            context_before: {
+                type: string;
+                description: string;
+            };
+            context_after: {
+                type: string;
+                description: string;
+            };
+            show: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            show_imports?: undefined;
+            show_docs?: undefined;
+            depth?: undefined;
+            symbol?: undefined;
+            start_line?: undefined;
+            end_line?: undefined;
+            context_lines?: undefined;
+            line?: undefined;
+            context?: undefined;
+            include_callers?: undefined;
+            include_tests?: undefined;
+            include_changes?: undefined;
+            paths?: undefined;
+            scope?: undefined;
+            kind?: undefined;
+            limit?: undefined;
+            lang?: undefined;
+            include?: undefined;
+            recursive?: undefined;
+            max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -142,6 +210,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             context_lines?: undefined;
             line?: undefined;
             context?: undefined;
@@ -156,6 +225,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -190,6 +260,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             line?: undefined;
@@ -205,6 +276,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -232,6 +304,13 @@ export declare const TOOL_DEFINITIONS: ({
                 type: string;
                 description: string;
             };
+            symbols: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
             line: {
                 type: string;
                 description: string;
@@ -269,6 +348,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -303,6 +383,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -318,6 +399,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -359,6 +441,10 @@ export declare const TOOL_DEFINITIONS: ({
                 type: string;
                 description: string;
             };
+            context_lines: {
+                type: string;
+                description: string;
+            };
             path?: undefined;
             show_imports?: undefined;
             show_docs?: undefined;
@@ -366,9 +452,9 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
-            context_lines?: undefined;
             line?: undefined;
             context?: undefined;
             include_callers?: undefined;
@@ -378,6 +464,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -413,6 +500,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -428,6 +516,7 @@ export declare const TOOL_DEFINITIONS: ({
             lang?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -458,6 +547,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -474,6 +564,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -512,6 +603,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -526,6 +618,7 @@ export declare const TOOL_DEFINITIONS: ({
             limit?: undefined;
             lang?: undefined;
             include?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -545,6 +638,10 @@ export declare const TOOL_DEFINITIONS: ({
     inputSchema: {
         type: "object";
         properties: {
+            verbose: {
+                type: string;
+                description: string;
+            };
             path?: undefined;
             show_imports?: undefined;
             show_docs?: undefined;
@@ -553,6 +650,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -608,6 +706,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -623,6 +722,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             check?: undefined;
             pattern?: undefined;
             name?: undefined;
@@ -669,6 +769,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -683,6 +784,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             ref?: undefined;
@@ -716,6 +818,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -732,6 +835,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             export_only?: undefined;
             pattern?: undefined;
             name?: undefined;
@@ -769,6 +873,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -784,6 +889,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -821,6 +927,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -836,6 +943,7 @@ export declare const TOOL_DEFINITIONS: ({
             lang?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -874,6 +982,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -890,6 +999,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -928,6 +1038,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -944,6 +1055,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;

package/dist/server/tool-definitions.js

@@ -10,6 +10,7 @@ export const MCP_INSTRUCTIONS = [
     '2. Starting work on a directory → explore_area (outline + imports + tests + git log in one call)',
     '3. Need to read a code file → smart_read (NOT Read/cat — returns structure, 60-80% fewer tokens)',
     '4. Need one function/class body → read_symbol (loads only that symbol, NOT the whole file)',
+    '4b. Need MULTIPLE function/class bodies from same file → read_symbols (batch — one call instead of N)',
     '5. Preparing an edit → read_for_edit (returns exact text for Edit old_string)',
     '6. Verify edits after editing → read_diff (only changed hunks — REQUIRES smart_read BEFORE editing)',
     '7. Multiple files at once → smart_read_many (batch up to 20 files)',
@@ -28,7 +29,7 @@ export const MCP_INSTRUCTIONS = [
     'WORKFLOWS:',
     '• Explore: project_overview → explore_area → smart_read → read_symbol',
     '• Edit: smart_read → read_for_edit → Edit → read_diff',
-    '• Refactor: find_usages → read_symbol → read_for_edit → Edit → test_summary',
+    '• Refactor: find_usages → read_symbols → read_for_edit → Edit → test_summary',
     '• Audit: code_audit + find_unused + Grep (for regex patterns)',
 ].join('\n');
 export const TOOL_DEFINITIONS = [
@@ -62,6 +63,25 @@ export const TOOL_DEFINITIONS = [
             required: ['path', 'symbol'],
         },
     },
+    {
+        name: 'read_symbols',
+        description: 'Batch read MULTIPLE symbols from ONE file in a single call — saves N-1 round-trips vs calling read_symbol N times. Returns all requested symbol bodies.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path' },
+                symbols: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Array of symbol names (max 10), e.g. ["UserService.create", "UserService.update", "UserService.delete"]',
+                },
+                context_before: { type: 'number', description: 'Lines of context before each symbol (default: 2)' },
+                context_after: { type: 'number', description: 'Lines of context after each symbol (default: 0)' },
+                show: { type: 'string', enum: ['full', 'head', 'tail', 'outline'], description: 'Display mode for each symbol (default: auto)' },
+            },
+            required: ['path', 'symbols'],
+        },
+    },
     {
         name: 'read_range',
         description: 'Read a specific line range from a file. Use when you know exact lines — lighter than reading the whole file.',
@@ -89,12 +109,17 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: 'read_for_edit',
-        description: 'Use INSTEAD OF Read when preparing an edit. Returns exact raw code around a symbol or line — copy directly as old_string for Edit tool. Optional: include_callers, include_tests, include_changes for enriched context.',
+        description: 'Use INSTEAD OF Read when preparing an edit. Returns exact raw code around a symbol or line — copy directly as old_string for Edit tool. Supports batch: pass "symbols" array to get multiple edit contexts in one call. Optional: include_callers, include_tests, include_changes for enriched context.',
         inputSchema: {
             type: 'object',
             properties: {
                 path: { type: 'string', description: 'File path' },
                 symbol: { type: 'string', description: 'Symbol name to edit (e.g. "UserService.updateUser")' },
+                symbols: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Array of symbol names for batch edit context (max 10). Alternative to single "symbol" — returns all symbols in one call.',
+                },
                 line: { type: 'number', description: 'Line number to edit (alternative to symbol)' },
                 context: { type: 'number', description: 'Lines of context around target (default: 5)' },
                 include_callers: { type: 'boolean', description: 'Show top callers of this symbol (saves a separate find_usages call)' },
@@ -122,7 +147,7 @@ export const TOOL_DEFINITIONS = [
     // --- Search & navigation ---
     {
         name: 'find_usages',
-        description: 'Use INSTEAD OF Grep for finding symbol references. Semantic search — groups by: definitions, imports, usages. Supports scope, kind, limit, lang filters.',
+        description: 'Use INSTEAD OF Grep for finding symbol references. Semantic search — groups by: definitions, imports, usages. Supports scope, kind, limit, lang filters. Use context_lines to include surrounding code.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -131,6 +156,7 @@ export const TOOL_DEFINITIONS = [
                 kind: { type: 'string', enum: ['definitions', 'imports', 'usages', 'all'], description: 'Show only specific section (default: "all")' },
                 limit: { type: 'number', description: 'Max results per category (default: 50, max: 500)' },
                 lang: { type: 'string', description: 'Filter by language/extension (e.g., "php", "typescript")' },
+                context_lines: { type: 'number', description: 'Lines of source context around each match (0-10). When set, shows surrounding code — saves follow-up read_symbol calls.' },
             },
             required: ['symbol'],
         },
@@ -176,10 +202,12 @@ export const TOOL_DEFINITIONS = [
     // --- Analytics ---
     {
         name: 'session_analytics',
-        description: 'Show token savings report: calls, tokens saved, per-tool breakdown, top files, cache hits.',
+        description: 'Show token savings report: calls, tokens saved, per-tool breakdown, top files, cache hits. Use verbose=true for full breakdown (per-intent, decision insights, savings by category).',
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                verbose: { type: 'boolean', description: 'Show detailed breakdown: per-intent, savings by category, decision insights (default: false)' },
+            },
         },
     },
     // --- Analysis ---