codesift-mcp 0.1.0 → 0.2.1

package/dist/register-tools.js

@@ -0,0 +1,1453 @@
+import { z } from "zod";
+/** Boolean that also accepts "true"/"false" strings (LLMs often send strings instead of booleans) */
+const zBool = () => z.union([z.boolean(), z.string().transform((s) => s === "true")]).optional();
+import { wrapTool, registerShortener } from "./server-helpers.js";
+import { indexFolder, indexFile, indexRepo, listAllRepos, invalidateCache } from "./tools/index-tools.js";
+import { searchSymbols, searchText, semanticSearch } from "./tools/search-tools.js";
+import { getFileTree, getFileOutline, getRepoOutline, suggestQueries } from "./tools/outline-tools.js";
+import { getSymbol, getSymbols, findAndShow, findReferences, findReferencesBatch, findDeadCode, getContextBundle, formatRefsCompact, formatSymbolCompact, formatSymbolsCompact, formatBundleCompact } from "./tools/symbol-tools.js";
+import { traceCallChain } from "./tools/graph-tools.js";
+import { impactAnalysis } from "./tools/impact-tools.js";
+import { traceRoute } from "./tools/route-tools.js";
+import { detectCommunities } from "./tools/community-tools.js";
+import { assembleContext, getKnowledgeMap } from "./tools/context-tools.js";
+import { diffOutline, changedSymbols } from "./tools/diff-tools.js";
+import { generateClaudeMd } from "./tools/generate-tools.js";
+import { codebaseRetrieval } from "./retrieval/codebase-retrieval.js";
+import { analyzeComplexity } from "./tools/complexity-tools.js";
+import { findClones } from "./tools/clone-tools.js";
+import { analyzeHotspots } from "./tools/hotspot-tools.js";
+import { crossRepoSearchSymbols, crossRepoFindReferences } from "./tools/cross-repo-tools.js";
+import { searchPatterns, listPatterns } from "./tools/pattern-tools.js";
+import { generateReport } from "./tools/report-tools.js";
+import { getUsageStats, formatUsageReport } from "./storage/usage-stats.js";
+import { goToDefinition, getTypeInfo, renameSymbol, getCallHierarchy } from "./lsp/lsp-tools.js";
+import { indexConversations, searchConversations, searchAllConversations, findConversationsForSymbol } from "./tools/conversation-tools.js";
+import { scanSecrets } from "./tools/secret-tools.js";
+import { consolidateMemories, readMemory } from "./tools/memory-tools.js";
+import { createAnalysisPlan, writeScratchpad, readScratchpad, listScratchpad, updateStepStatus, getPlan, listPlans } from "./tools/coordinator-tools.js";
+import { frequencyAnalysis } from "./tools/frequency-tools.js";
+import { reviewDiff } from "./tools/review-diff-tools.js";
+import { formatComplexityCompact, formatComplexityCounts, formatClonesCompact, formatClonesCounts, formatHotspotsCompact, formatHotspotsCounts } from "./formatters-shortening.js";
+import { formatSearchSymbols, formatFileTree, formatFileOutline, formatSearchPatterns, formatDeadCode, formatComplexity, formatClones, formatHotspots, formatRepoOutline, formatSuggestQueries, formatSecrets, formatConversations, formatRoles, formatAssembleContext, formatCommunities, formatCallTree, formatTraceRoute, formatKnowledgeMap, formatImpactAnalysis, formatDiffOutline, formatChangedSymbols, formatReviewDiff } from "./formatters.js";
+const zFiniteNumber = z.number().finite();
+/** Coerce string→number for numeric params while rejecting NaN/empty strings. */
+export const zNum = () => z.union([
+    zFiniteNumber,
+    z.string()
+        .trim()
+        .min(1, "Expected a number")
+        .transform((value) => Number(value))
+        .pipe(zFiniteNumber),
+]).optional();
+// ---------------------------------------------------------------------------
+// Registered tool handles — populated by registerTools(), used by describe_tools reveal
+// ---------------------------------------------------------------------------
+const toolHandles = new Map();
+/** Get a registered tool handle by name (for testing and describe_tools reveal) */
+export function getToolHandle(name) {
+    return toolHandles.get(name);
+}
+// ---------------------------------------------------------------------------
+// Output schemas — typed results for structured validation & documentation
+// ---------------------------------------------------------------------------
+export const OutputSchemas = {
+    /** search_symbols, cross_repo_search */
+    searchResults: z.string().describe("Formatted search results: file:line kind name signature"),
+    /** get_file_tree */
+    fileTree: z.string().describe("File tree with symbol counts per file"),
+    /** get_file_outline */
+    fileOutline: z.string().describe("Symbol outline: line:end_line kind name"),
+    /** get_symbol */
+    symbol: z.string().nullable().describe("Symbol source code or null if not found"),
+    /** find_references */
+    references: z.string().describe("References in file:line: context format"),
+    /** trace_call_chain */
+    callTree: z.string().describe("Call tree hierarchy or Mermaid diagram"),
+    /** impact_analysis */
+    impactAnalysis: z.string().describe("Changed files and affected symbols with risk levels"),
+    /** codebase_retrieval */
+    batchResults: z.string().describe("Concatenated sub-query result sections"),
+    /** discover_tools */
+    toolDiscovery: z.object({
+        query: z.string(),
+        matches: z.array(z.object({
+            name: z.string(),
+            category: z.string(),
+            description: z.string(),
+            is_core: z.boolean(),
+        })),
+        total_tools: z.number(),
+        categories: z.array(z.string()),
+    }),
+    /** get_call_hierarchy */
+    callHierarchy: z.string().describe("Call hierarchy: symbol with incoming and outgoing calls"),
+    /** analyze_complexity */
+    complexity: z.string().describe("Complexity report: CC nest lines file:line name"),
+    /** find_dead_code */
+    deadCode: z.string().describe("Unused exported symbols list"),
+    /** find_clones */
+    clones: z.string().describe("Code clone pairs with similarity scores"),
+    /** scan_secrets */
+    secrets: z.string().describe("Secret findings with severity, type, and masked values"),
+    /** go_to_definition */
+    definition: z.string().nullable().describe("file:line (via lsp|index) with preview"),
+    /** get_type_info */
+    typeInfo: z.union([
+        z.object({ type: z.string(), documentation: z.string().optional(), via: z.literal("lsp") }),
+        z.object({ via: z.literal("unavailable"), hint: z.string() }),
+    ]),
+    /** rename_symbol */
+    renameResult: z.object({
+        files_changed: z.number(),
+        edits: z.array(z.object({ file: z.string(), changes: z.number() })),
+    }),
+    /** usage_stats */
+    usageStats: z.object({ report: z.string() }),
+    /** list_repos */
+    repoList: z.union([z.array(z.string()), z.array(z.object({ name: z.string() }).passthrough())]),
+};
+/** Tools always registered with full schema — top 10 by usage (91% of calls) + essentials */
+const CORE_TOOL_NAMES = new Set([
+    "search_text", // #1: 1536 calls, 36%
+    "codebase_retrieval", // #2: 510 calls, 12%
+    "get_file_outline", // #3: 342 calls, 8%
+    "search_symbols", // #4: 321 calls, 8%
+    "list_repos", // #5: 223 calls, 5%
+    "get_file_tree", // #6: 218 calls, 5%
+    "index_file", // #7: 163 calls, 4% — lightweight schema
+    "get_symbol", // #8: 135 calls, 3%
+    "index_conversations", // #9: 125 calls, 3% — lightweight schema
+    "search_patterns", // #10: 122 calls, 3%
+    "index_folder", // essential: repo onboarding
+    "discover_tools", // meta: discovers deferred tools
+]);
+/** Get all tool definitions (exported for testing) */
+export function getToolDefinitions() {
+    return TOOL_DEFINITIONS;
+}
+// ---------------------------------------------------------------------------
+// Tool definitions — data-driven registration (CQ14: eliminates 30× boilerplate)
+// ---------------------------------------------------------------------------
+const TOOL_DEFINITIONS = [
+    // --- Indexing ---
+    {
+        name: "index_folder",
+        category: "indexing",
+        searchHint: "index local folder directory project parse symbols",
+        description: "Index a local folder, extracting symbols and building the search index",
+        schema: {
+            path: z.string().describe("Absolute path to the folder to index"),
+            incremental: zBool().describe("Only re-index changed files"),
+            include_paths: z.union([z.array(z.string()), z.string().transform((s) => JSON.parse(s))]).optional().describe("Glob patterns to include. Can be passed as JSON string."),
+        },
+        handler: (args) => indexFolder(args.path, {
+            incremental: args.incremental,
+            include_paths: args.include_paths,
+        }),
+    },
+    {
+        name: "index_repo",
+        category: "indexing",
+        searchHint: "clone remote git repository index",
+        description: "Clone and index a remote git repository",
+        schema: {
+            url: z.string().describe("Git clone URL"),
+            branch: z.string().optional().describe("Branch to checkout"),
+            include_paths: z.union([z.array(z.string()), z.string().transform((s) => JSON.parse(s))]).optional().describe("Glob patterns to include. Can be passed as JSON string."),
+        },
+        handler: (args) => indexRepo(args.url, {
+            branch: args.branch,
+            include_paths: args.include_paths,
+        }),
+    },
+    {
+        name: "list_repos",
+        category: "indexing",
+        searchHint: "list indexed repositories repos available",
+        outputSchema: OutputSchemas.repoList,
+        description: "List indexed repos. Set compact=false for full metadata. Cached per session.",
+        schema: {
+            compact: zBool().describe("true=names only (default), false=full metadata"),
+        },
+        handler: (args) => listAllRepos({ compact: args.compact ?? true }),
+    },
+    {
+        name: "invalidate_cache",
+        category: "indexing",
+        searchHint: "clear cache invalidate re-index refresh",
+        description: "Clear the index cache for a repository, forcing full re-index on next use",
+        schema: {
+            repo: z.string().describe("Repository identifier (e.g. local/my-project)"),
+        },
+        handler: (args) => invalidateCache(args.repo),
+    },
+    {
+        name: "index_file",
+        category: "indexing",
+        searchHint: "re-index single file update incremental",
+        description: "Re-index a single file after editing. Auto-finds repo, skips if unchanged.",
+        schema: {
+            path: z.string().describe("Absolute path to the file to re-index"),
+        },
+        handler: (args) => indexFile(args.path),
+    },
+    // --- Search ---
+    {
+        name: "search_symbols",
+        category: "search",
+        searchHint: "search find symbols functions classes types methods by name signature",
+        outputSchema: OutputSchemas.searchResults,
+        description: "Search symbols by name/signature. detail_level: compact (~15 tok), standard (default), full.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            query: z.string().describe("Search query string"),
+            kind: z.string().optional().describe("Filter by symbol kind (function, class, etc.)"),
+            file_pattern: z.string().optional().describe("Glob pattern to filter files"),
+            include_source: zBool().describe("Include full source code of each symbol"),
+            top_k: zNum().describe("Maximum number of results to return (default 50)"),
+            source_chars: zNum().describe("Truncate each symbol's source to N characters (reduces output size)"),
+            detail_level: z.enum(["compact", "standard", "full"]).optional().describe("compact (~15 tok), standard (default), full (all source)"),
+            token_budget: zNum().describe("Max tokens for results — greedily packs results until budget exhausted. Overrides top_k."),
+            rerank: zBool().describe("Rerank results using cross-encoder model for improved relevance (requires @huggingface/transformers)"),
+        },
+        handler: async (args) => {
+            const results = await searchSymbols(args.repo, args.query, {
+                kind: args.kind,
+                file_pattern: args.file_pattern,
+                include_source: args.include_source,
+                top_k: args.top_k,
+                source_chars: args.source_chars,
+                detail_level: args.detail_level,
+                token_budget: args.token_budget,
+                rerank: args.rerank,
+            });
+            return formatSearchSymbols(results);
+        },
+    },
+    {
+        name: "ast_query",
+        category: "search",
+        searchHint: "AST tree-sitter query structural pattern matching code shape",
+        description: "Search AST patterns via tree-sitter S-expressions. Finds code by structural shape.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            query: z.string().describe("Tree-sitter query in S-expression syntax"),
+            language: z.string().describe("Tree-sitter grammar: typescript, javascript, python, go, rust, java, ruby, php"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            max_matches: zNum().describe("Maximum matches to return (default: 50)"),
+        },
+        handler: async (args) => {
+            const { astQuery } = await import("./tools/ast-query-tools.js");
+            return astQuery(args.repo, args.query, {
+                language: args.language,
+                file_pattern: args.file_pattern,
+                max_matches: args.max_matches,
+            });
+        },
+    },
+    {
+        name: "semantic_search",
+        category: "search",
+        searchHint: "semantic meaning intent concept embedding vector natural language",
+        description: "Search code by meaning using embeddings. For intent-based queries: 'error handling', 'auth flow'. Requires indexed embeddings.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            query: z.string().describe("Natural language query describing what you're looking for"),
+            top_k: zNum().describe("Number of results (default: 10)"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            exclude_tests: zBool().describe("Exclude test files from results"),
+            rerank: zBool().describe("Re-rank results with cross-encoder for better precision"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.top_k != null)
+                opts.top_k = args.top_k;
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.exclude_tests != null)
+                opts.exclude_tests = args.exclude_tests;
+            if (args.rerank != null)
+                opts.rerank = args.rerank;
+            return semanticSearch(args.repo, args.query, opts);
+        },
+    },
+    {
+        name: "search_text",
+        category: "search",
+        searchHint: "full-text search grep regex keyword content files",
+        description: "Full-text search across all files. For conceptual queries use semantic_search.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            query: z.string().describe("Search query or regex pattern"),
+            regex: zBool().describe("Treat query as a regex pattern"),
+            context_lines: zNum().describe("Number of context lines around each match"),
+            file_pattern: z.string().optional().describe("Glob pattern to filter files"),
+            max_results: zNum().describe("Maximum number of matching lines to return (default 200)"),
+            group_by_file: zBool().describe("Group by file: {file, count, lines[], first_match}. ~80% less output."),
+            auto_group: zBool().describe("Auto group_by_file when >50 matches."),
+            ranked: z.boolean().optional().describe("Classify hits by containing symbol and rank by centrality"),
+        },
+        handler: (args) => searchText(args.repo, args.query, {
+            regex: args.regex,
+            context_lines: args.context_lines,
+            file_pattern: args.file_pattern,
+            max_results: args.max_results,
+            group_by_file: args.group_by_file,
+            auto_group: args.auto_group,
+            ranked: args.ranked,
+        }),
+    },
+    // --- Outline ---
+    {
+        name: "get_file_tree",
+        category: "outline",
+        searchHint: "file tree directory structure listing files symbols",
+        outputSchema: OutputSchemas.fileTree,
+        description: "File tree with symbol counts. compact=true for flat list (10-50x less output). Cached 5min.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            path_prefix: z.string().optional().describe("Filter to a subtree by path prefix"),
+            name_pattern: z.string().optional().describe("Glob pattern to filter file names"),
+            depth: zNum().describe("Maximum directory depth to traverse"),
+            compact: zBool().describe("Return flat list of {path, symbols} instead of nested tree (much less output)"),
+            min_symbols: zNum().describe("Only include files with at least this many symbols"),
+        },
+        handler: async (args) => {
+            const result = await getFileTree(args.repo, {
+                path_prefix: args.path_prefix,
+                name_pattern: args.name_pattern,
+                depth: args.depth,
+                compact: args.compact,
+                min_symbols: args.min_symbols,
+            });
+            return formatFileTree(result);
+        },
+    },
+    {
+        name: "get_file_outline",
+        category: "outline",
+        searchHint: "file outline symbols functions classes exports single file",
+        outputSchema: OutputSchemas.fileOutline,
+        description: "Get the symbol outline of a single file (functions, classes, exports)",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            file_path: z.string().describe("Relative file path within the repository"),
+        },
+        handler: async (args) => {
+            const result = await getFileOutline(args.repo, args.file_path);
+            return formatFileOutline(result);
+        },
+    },
+    {
+        name: "get_repo_outline",
+        category: "outline",
+        searchHint: "repository outline overview directory structure high-level",
+        description: "Get a high-level outline of the entire repository grouped by directory",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+        },
+        handler: async (args) => {
+            const result = await getRepoOutline(args.repo);
+            return formatRepoOutline(result);
+        },
+    },
+    {
+        name: "suggest_queries",
+        category: "outline",
+        searchHint: "suggest queries explore unfamiliar repo onboarding first call",
+        description: "Suggest queries for exploring a new repo. Returns top files, kind distribution, examples.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+        },
+        handler: async (args) => {
+            const result = await suggestQueries(args.repo);
+            return formatSuggestQueries(result);
+        },
+    },
+    // --- Symbol retrieval ---
+    {
+        name: "get_symbol",
+        category: "symbols",
+        searchHint: "get retrieve single symbol source code by ID",
+        outputSchema: OutputSchemas.symbol,
+        description: "Get symbol by ID with source. Auto-prefetches children for classes. For batch: get_symbols. For context: get_context_bundle.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            symbol_id: z.string().describe("Unique symbol identifier"),
+            include_related: zBool().describe("Include children/related symbols (default: true)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.include_related != null)
+                opts.include_related = args.include_related;
+            const result = await getSymbol(args.repo, args.symbol_id, opts);
+            if (!result)
+                return null;
+            let text = formatSymbolCompact(result.symbol);
+            if (result.related && result.related.length > 0) {
+                text += "\n\n--- children ---\n" + result.related.map((s) => `${s.kind} ${s.name}${s.signature ? s.signature : ""} [${s.file}:${s.start_line}]`).join("\n");
+            }
+            return text;
+        },
+    },
+    {
+        name: "get_symbols",
+        category: "symbols",
+        searchHint: "batch get multiple symbols by IDs",
+        description: "Retrieve multiple symbols by ID in a single batch call",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            symbol_ids: z.union([
+                z.array(z.string()),
+                z.string().transform((s) => JSON.parse(s)),
+            ]).describe("Array of symbol identifiers. Can be passed as JSON string."),
+        },
+        handler: async (args) => {
+            const syms = await getSymbols(args.repo, args.symbol_ids);
+            return formatSymbolsCompact(syms);
+        },
+    },
+    {
+        name: "find_and_show",
+        category: "symbols",
+        searchHint: "find symbol by name show source code references",
+        description: "Find a symbol by name and show its source, optionally including references",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            query: z.string().describe("Symbol name or query to search for"),
+            include_refs: zBool().describe("Include locations that reference this symbol"),
+        },
+        handler: async (args) => {
+            const result = await findAndShow(args.repo, args.query, args.include_refs);
+            if (!result)
+                return null;
+            let text = formatSymbolCompact(result.symbol);
+            if (result.references) {
+                text += `\n\n--- references ---\n${formatRefsCompact(result.references)}`;
+            }
+            return text;
+        },
+    },
+    {
+        name: "get_context_bundle",
+        category: "symbols",
+        searchHint: "context bundle symbol imports siblings callers one call",
+        description: "Symbol + imports + siblings in one call. Saves 2-3 round-trips.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            symbol_name: z.string().describe("Symbol name to find"),
+        },
+        handler: async (args) => {
+            const bundle = await getContextBundle(args.repo, args.symbol_name);
+            if (!bundle)
+                return null;
+            return formatBundleCompact(bundle);
+        },
+    },
+    // --- References & call graph ---
+    {
+        name: "find_references",
+        category: "graph",
+        searchHint: "find references usages callers who uses symbol",
+        outputSchema: OutputSchemas.references,
+        description: "Find all references to a symbol. Pass symbol_names array for batch search.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            symbol_name: z.string().optional().describe("Name of the symbol to find references for"),
+            symbol_names: z.union([z.array(z.string()), z.string().transform((s) => JSON.parse(s))]).optional()
+                .describe("Array of symbol names for batch search (reads each file once). Can be JSON string."),
+            file_pattern: z.string().optional().describe("Glob pattern to filter files"),
+        },
+        handler: async (args) => {
+            const names = args.symbol_names;
+            if (names && names.length > 0) {
+                return findReferencesBatch(args.repo, names, args.file_pattern);
+            }
+            const refs = await findReferences(args.repo, args.symbol_name, args.file_pattern);
+            // Compact format: drop col, use file:line: context (matches grep output)
+            return formatRefsCompact(refs);
+        },
+    },
+    {
+        name: "trace_call_chain",
+        category: "graph",
+        searchHint: "trace call chain callers callees dependency graph mermaid",
+        outputSchema: OutputSchemas.callTree,
+        description: "Trace call chain: callers or callees. output_format='mermaid' for diagram.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            symbol_name: z.string().describe("Name of the symbol to trace"),
+            direction: z.enum(["callers", "callees"]).describe("Trace direction"),
+            depth: zNum().describe("Maximum depth to traverse the call graph (default: 1)"),
+            include_source: zBool().describe("Include full source code of each symbol (default: false)"),
+            include_tests: zBool().describe("Include test files in trace results (default: false)"),
+            output_format: z.enum(["json", "mermaid"]).optional().describe("Output format: 'json' (default) or 'mermaid' (flowchart diagram)"),
+        },
+        handler: async (args) => {
+            const result = await traceCallChain(args.repo, args.symbol_name, args.direction, {
+                depth: args.depth,
+                include_source: args.include_source,
+                include_tests: args.include_tests,
+                output_format: args.output_format,
+            });
+            return formatCallTree(result);
+        },
+    },
+    {
+        name: "impact_analysis",
+        category: "graph",
+        searchHint: "impact analysis blast radius git changes affected symbols",
+        outputSchema: OutputSchemas.impactAnalysis,
+        description: "Blast radius of git changes — affected symbols and files.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            since: z.string().describe("Git ref to compare from (e.g. HEAD~3, commit SHA, branch)"),
+            depth: zNum().describe("Depth of dependency traversal"),
+            until: z.string().optional().describe("Git ref to compare to (defaults to HEAD)"),
+            include_source: zBool().describe("Include full source code of affected symbols (default: false)"),
+        },
+        handler: async (args) => {
+            const result = await impactAnalysis(args.repo, args.since, {
+                depth: args.depth,
+                until: args.until,
+                include_source: args.include_source,
+            });
+            return formatImpactAnalysis(result);
+        },
+    },
+    {
+        name: "trace_route",
+        category: "graph",
+        searchHint: "trace HTTP route handler API endpoint service database NestJS Express Next.js",
+        description: "Trace HTTP route → handler → service → DB. NestJS, Next.js, Express.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            path: z.string().describe("URL path to trace (e.g. '/api/users', '/api/projects/:id')"),
+            output_format: z.enum(["json", "mermaid"]).optional().describe("Output format: 'json' (default) or 'mermaid' (sequence diagram)"),
+        },
+        handler: async (args) => {
+            const result = await traceRoute(args.repo, args.path, args.output_format);
+            return formatTraceRoute(result);
+        },
+    },
+    {
+        name: "go_to_definition",
+        category: "lsp",
+        searchHint: "go to definition jump navigate LSP language server",
+        outputSchema: OutputSchemas.definition,
+        description: "Go to the definition of a symbol. Uses LSP when available for type-safe precision, falls back to index search.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            symbol_name: z.string().describe("Symbol name to find definition of"),
+            file_path: z.string().optional().describe("File containing the symbol reference (for LSP precision)"),
+            line: zNum().describe("0-based line number of the reference"),
+            character: zNum().describe("0-based column of the reference"),
+        },
+        handler: async (args) => {
+            const result = await goToDefinition(args.repo, args.symbol_name, args.file_path, args.line, args.character);
+            if (!result)
+                return null;
+            const preview = result.preview ? `\n${result.preview}` : "";
+            return `${result.file}:${result.line + 1} (via ${result.via})${preview}`;
+        },
+    },
+    {
+        name: "get_type_info",
+        category: "lsp",
+        searchHint: "type information hover documentation return type parameters LSP",
+        outputSchema: OutputSchemas.typeInfo,
+        description: "Get type info via LSP hover (return type, params, docs). Hint if LSP unavailable.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            symbol_name: z.string().describe("Symbol name to get type info for"),
+            file_path: z.string().optional().describe("File containing the symbol"),
+            line: zNum().describe("0-based line number"),
+            character: zNum().describe("0-based column"),
+        },
+        handler: (args) => getTypeInfo(args.repo, args.symbol_name, args.file_path, args.line, args.character),
+    },
+    {
+        name: "rename_symbol",
+        category: "lsp",
+        searchHint: "rename symbol refactor LSP type-safe all files",
+        outputSchema: OutputSchemas.renameResult,
+        description: "Rename symbol across all files via LSP. Type-safe, updates imports/refs.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            symbol_name: z.string().describe("Current name of the symbol to rename"),
+            new_name: z.string().describe("New name for the symbol"),
+            file_path: z.string().optional().describe("File containing the symbol"),
+            line: zNum().describe("0-based line number"),
+            character: zNum().describe("0-based column"),
+        },
+        handler: (args) => renameSymbol(args.repo, args.symbol_name, args.new_name, args.file_path, args.line, args.character),
+    },
+    {
+        name: "get_call_hierarchy",
+        category: "lsp",
+        searchHint: "call hierarchy incoming outgoing calls who calls what calls LSP callers callees",
+        outputSchema: OutputSchemas.callHierarchy,
+        description: "LSP call hierarchy: incoming + outgoing calls. Complements trace_call_chain.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            symbol_name: z.string().describe("Symbol name to get call hierarchy for"),
+            file_path: z.string().optional().describe("File containing the symbol (for LSP precision)"),
+            line: zNum().describe("0-based line number"),
+            character: zNum().describe("0-based column"),
+        },
+        handler: async (args) => {
+            const result = await getCallHierarchy(args.repo, args.symbol_name, args.file_path, args.line, args.character);
+            if (result.via === "unavailable") {
+                return { ...result };
+            }
+            // Compact text format
+            const lines = [];
+            lines.push(`${result.symbol.kind} ${result.symbol.name} (${result.symbol.file}:${result.symbol.line})`);
+            if (result.incoming.length > 0) {
+                lines.push(`\n--- incoming calls (${result.incoming.length}) ---`);
+                for (const c of result.incoming) {
+                    lines.push(`  ${c.kind} ${c.name} (${c.file}:${c.line})`);
+                }
+            }
+            if (result.outgoing.length > 0) {
+                lines.push(`\n--- outgoing calls (${result.outgoing.length}) ---`);
+                for (const c of result.outgoing) {
+                    lines.push(`  ${c.kind} ${c.name} (${c.file}:${c.line})`);
+                }
+            }
+            if (result.incoming.length === 0 && result.outgoing.length === 0) {
+                lines.push("\nNo incoming or outgoing calls found.");
+            }
+            return lines.join("\n");
+        },
+    },
+    {
+        name: "detect_communities",
+        category: "architecture",
+        searchHint: "community detection clusters modules Louvain import graph boundaries",
+        description: "Louvain community detection on import graph. Discovers module boundaries.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            focus: z.string().optional().describe("Path substring to filter files (e.g. 'src/lib')"),
+            resolution: zNum().describe("Louvain resolution: higher = more smaller communities, lower = fewer larger (default: 1.0)"),
+            output_format: z.enum(["json", "mermaid"]).optional().describe("Output format: 'json' (default) or 'mermaid' (graph diagram)"),
+        },
+        handler: async (args) => {
+            const result = await detectCommunities(args.repo, args.focus, args.resolution, args.output_format);
+            return formatCommunities(result);
+        },
+    },
+    {
+        name: "find_circular_deps",
+        category: "architecture",
+        searchHint: "circular dependency cycle import loop detection",
+        description: "Detect circular dependencies in the import graph via DFS. Returns file-level cycles.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            max_cycles: zNum().describe("Maximum cycles to report (default: 50)"),
+        },
+        handler: async (args) => {
+            const { findCircularDeps } = await import("./tools/graph-tools.js");
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.max_cycles != null)
+                opts.max_cycles = args.max_cycles;
+            const result = await findCircularDeps(args.repo, opts);
+            if (result.cycles.length === 0) {
+                return `No circular dependencies found (scanned ${result.total_files} files, ${result.total_edges} edges)`;
+            }
+            const lines = [`${result.cycles.length} circular dependencies found (${result.total_files} files, ${result.total_edges} edges):\n`];
+            for (const c of result.cycles) {
+                lines.push(`  ${c.cycle.join(" → ")}`);
+            }
+            return lines.join("\n");
+        },
+    },
+    {
+        name: "check_boundaries",
+        category: "architecture",
+        searchHint: "boundary rules architecture enforcement imports CI gate hexagonal onion",
+        description: "Check architecture boundary rules against imports. Path substring matching.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            rules: z.array(z.object({
+                from: z.string().describe("Path substring matching source files (e.g. 'src/domain')"),
+                cannot_import: z.array(z.string()).optional().describe("Path patterns that matched files must NOT import"),
+                can_only_import: z.array(z.string()).optional().describe("Path patterns that matched files may ONLY import (allowlist)"),
+            })).describe("Array of boundary rules to check"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+        },
+        handler: async (args) => {
+            const { checkBoundaries } = await import("./tools/boundary-tools.js");
+            return checkBoundaries(args.repo, args.rules, { file_pattern: args.file_pattern });
+        },
+    },
+    {
+        name: "classify_roles",
+        category: "architecture",
+        searchHint: "classify roles entry core utility dead leaf symbol architecture",
+        description: "Classify symbol roles (entry/core/utility/dead/leaf) by call graph connectivity.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            include_tests: zBool().describe("Include test files (default: false)"),
+            top_n: zNum().describe("Maximum number of symbols to return (default: 100)"),
+        },
+        handler: async (args) => {
+            const { classifySymbolRoles } = await import("./tools/graph-tools.js");
+            const result = await classifySymbolRoles(args.repo, {
+                file_pattern: args.file_pattern,
+                include_tests: args.include_tests,
+                top_n: args.top_n,
+            });
+            return formatRoles(result);
+        },
+    },
+    // --- Context & knowledge ---
+    {
+        name: "assemble_context",
+        category: "context",
+        searchHint: "assemble context token budget L0 L1 L2 L3 source signatures summaries",
+        description: "Assemble code context within token budget. L0=source, L1=signatures, L2=files, L3=dirs.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            query: z.string().describe("Natural language query describing what context is needed"),
+            token_budget: zNum().describe("Maximum tokens for the assembled context"),
+            level: z.enum(["L0", "L1", "L2", "L3"]).optional().describe("L0=source (default), L1=signatures, L2=files, L3=dirs"),
+            rerank: zBool().describe("Rerank results using cross-encoder model for improved relevance (requires @huggingface/transformers)"),
+        },
+        handler: async (args) => {
+            const result = await assembleContext(args.repo, args.query, args.token_budget, args.level, args.rerank);
+            return formatAssembleContext(result);
+        },
+    },
+    {
+        name: "get_knowledge_map",
+        category: "context",
+        searchHint: "knowledge map module dependency graph architecture overview mermaid",
+        description: "Get the module dependency map showing how files and directories relate",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            focus: z.string().optional().describe("Focus on a specific module or directory"),
+            depth: zNum().describe("Maximum depth of the dependency graph"),
+            output_format: z.enum(["json", "mermaid"]).optional().describe("Output format: 'json' (default) or 'mermaid' (dependency diagram)"),
+        },
+        handler: async (args) => {
+            const result = await getKnowledgeMap(args.repo, args.focus, args.depth, args.output_format);
+            return formatKnowledgeMap(result);
+        },
+    },
+    // --- Diff ---
+    {
+        name: "diff_outline",
+        category: "diff",
+        searchHint: "diff outline structural changes git refs compare",
+        description: "Get a structural outline of what changed between two git refs",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            since: z.string().describe("Git ref to compare from"),
+            until: z.string().optional().describe("Git ref to compare to (defaults to HEAD)"),
+        },
+        handler: async (args) => {
+            const result = await diffOutline(args.repo, args.since, args.until);
+            return formatDiffOutline(result);
+        },
+    },
+    {
+        name: "changed_symbols",
+        category: "diff",
+        searchHint: "changed symbols added modified removed git diff",
+        description: "List symbols that were added, modified, or removed between two git refs",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            since: z.string().describe("Git ref to compare from"),
+            until: z.string().optional().describe("Git ref to compare to (defaults to HEAD)"),
+            include_diff: zBool().describe("Include unified diff per changed file (truncated to 500 chars)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (args.include_diff === true)
+                opts.include_diff = true;
+            const result = await changedSymbols(args.repo, args.since, args.until, opts);
+            return formatChangedSymbols(result);
+        },
+    },
+    // --- Generation ---
+    {
+        name: "generate_claude_md",
+        category: "reporting",
+        searchHint: "generate CLAUDE.md project summary documentation",
+        description: "Generate a CLAUDE.md project summary file from the repository index",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            output_path: z.string().optional().describe("Custom output file path"),
+        },
+        handler: (args) => generateClaudeMd(args.repo, args.output_path),
+    },
+    // --- Batch retrieval ---
+    {
+        name: "codebase_retrieval",
+        category: "search",
+        searchHint: "batch retrieval multi-query semantic hybrid token budget",
+        outputSchema: OutputSchemas.batchResults,
+        description: "Batch multi-query retrieval with shared token budget. Supports symbols/text/semantic/hybrid.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            queries: z
+                .union([
+                z.array(z.object({ type: z.string() }).passthrough()),
+                z.string().transform((s) => JSON.parse(s)),
+            ])
+                .describe("Sub-queries array (symbols/text/file_tree/outline/references/call_chain/impact/context/knowledge_map). JSON string OK."),
+            token_budget: zNum().describe("Maximum total tokens across all sub-query results"),
+        },
+        handler: async (args) => {
+            const result = await codebaseRetrieval(args.repo, args.queries, args.token_budget);
+            // Format as text sections instead of JSON envelope
+            const sections = result.results.map((r) => {
+                const dataStr = typeof r.data === "string" ? r.data : JSON.stringify(r.data);
+                return `--- ${r.type} ---\n${dataStr}`;
+            });
+            let output = sections.join("\n\n");
+            if (result.truncated)
+                output += "\n\n(truncated: token budget exceeded)";
+            return output;
+        },
+    },
+    // --- Analysis ---
+    {
+        name: "find_dead_code",
+        category: "analysis",
+        searchHint: "dead code unused exports unreferenced symbols cleanup",
+        outputSchema: OutputSchemas.deadCode,
+        description: "Find dead code: exported symbols with zero external references.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            include_tests: zBool().describe("Include test files in scan (default: false)"),
+        },
+        handler: async (args) => {
+            const result = await findDeadCode(args.repo, {
+                file_pattern: args.file_pattern,
+                include_tests: args.include_tests,
+            });
+            return formatDeadCode(result);
+        },
+    },
+    {
+        name: "find_unused_imports",
+        category: "analysis",
+        searchHint: "unused imports dead cleanup lint",
+        description: "Find imported names never referenced in the file body. Complements find_dead_code.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            include_tests: zBool().describe("Include test files in scan (default: false)"),
+        },
+        handler: async (args) => {
+            const { findUnusedImports } = await import("./tools/symbol-tools.js");
+            const opts = {};
+            if (args.file_pattern != null)
+                opts.file_pattern = args.file_pattern;
+            if (args.include_tests != null)
+                opts.include_tests = args.include_tests;
+            const result = await findUnusedImports(args.repo, opts);
+            if (result.unused.length === 0) {
+                return `No unused imports found (scanned ${result.scanned_files} files)`;
+            }
+            const lines = [`${result.unused.length} unused imports (${result.scanned_files} files scanned)${result.truncated ? " [truncated]" : ""}:\n`];
+            for (const u of result.unused) {
+                lines.push(`  ${u.file}:${u.line} — "${u.imported_name}"`);
+            }
+            return lines.join("\n");
+        },
+    },
+    {
+        name: "analyze_complexity",
+        category: "analysis",
+        searchHint: "complexity cyclomatic nesting refactoring functions",
+        outputSchema: OutputSchemas.complexity,
+        description: "Top N most complex functions by cyclomatic complexity, nesting, lines.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            top_n: zNum().describe("Return top N most complex functions (default: 30)"),
+            min_complexity: zNum().describe("Minimum cyclomatic complexity to include (default: 1)"),
+            include_tests: zBool().describe("Include test files (default: false)"),
+        },
+        handler: async (args) => {
+            const result = await analyzeComplexity(args.repo, {
+                file_pattern: args.file_pattern,
+                top_n: args.top_n,
+                min_complexity: args.min_complexity,
+                include_tests: args.include_tests,
+            });
+            return formatComplexity(result);
+        },
+    },
+    {
+        name: "find_clones",
+        category: "analysis",
+        searchHint: "code clones duplicates copy-paste detection similar functions",
+        outputSchema: OutputSchemas.clones,
+        description: "Find code clones: similar function pairs via hash bucketing + line-similarity.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            min_similarity: zNum().describe("Minimum similarity threshold 0-1 (default: 0.7)"),
+            min_lines: zNum().describe("Minimum normalized lines to consider (default: 10)"),
+            include_tests: zBool().describe("Include test files (default: false)"),
+        },
+        handler: async (args) => {
+            const result = await findClones(args.repo, {
+                file_pattern: args.file_pattern,
+                min_similarity: args.min_similarity,
+                min_lines: args.min_lines,
+                include_tests: args.include_tests,
+            });
+            return formatClones(result);
+        },
+    },
+    {
+        name: "frequency_analysis",
+        category: "analysis",
+        searchHint: "frequency analysis common patterns AST shape clusters",
+        description: "Group functions by normalized AST shape. Finds emergent patterns invisible to regex.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            top_n: zNum().optional().describe("Number of clusters to return (default: 30)"),
+            min_nodes: zNum().optional().describe("Minimum AST nodes in a subtree to include (default: 5)"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            kind: z.string().optional().describe("Filter by symbol kind, comma-separated (default: function,method)"),
+            include_tests: zBool().describe("Include test files (default: false)"),
+            token_budget: zNum().optional().describe("Max tokens for response"),
+        },
+        handler: async (args) => frequencyAnalysis(args.repo, {
+            top_n: args.top_n,
+            min_nodes: args.min_nodes,
+            file_pattern: args.file_pattern,
+            kind: args.kind,
+            include_tests: args.include_tests,
+            token_budget: args.token_budget,
+        }),
+    },
+    {
+        name: "analyze_hotspots",
+        category: "analysis",
+        searchHint: "hotspots git churn bug-prone change frequency complexity",
+        description: "Git churn hotspots: change frequency × complexity. Higher score = more bug-prone.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            since_days: zNum().describe("Look back N days (default: 90)"),
+            top_n: zNum().describe("Return top N hotspots (default: 30)"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+        },
+        handler: async (args) => {
+            const result = await analyzeHotspots(args.repo, {
+                since_days: args.since_days,
+                top_n: args.top_n,
+                file_pattern: args.file_pattern,
+            });
+            return formatHotspots(result);
+        },
+    },
+    // --- Cross-repo ---
+    {
+        name: "cross_repo_search",
+        category: "cross-repo",
+        searchHint: "cross-repo search symbols across all repositories monorepo microservice",
+        description: "Search symbols across ALL indexed repositories. Useful for monorepos and microservice architectures.",
+        schema: {
+            query: z.string().describe("Symbol search query"),
+            repo_pattern: z.string().optional().describe("Filter repos by name pattern (e.g. 'local/tgm')"),
+            kind: z.string().optional().describe("Filter by symbol kind"),
+            top_k: zNum().describe("Max results per repo (default: 10)"),
+            include_source: zBool().describe("Include source code"),
+        },
+        handler: (args) => crossRepoSearchSymbols(args.query, {
+            repo_pattern: args.repo_pattern,
+            kind: args.kind,
+            top_k: args.top_k,
+            include_source: args.include_source,
+        }),
+    },
+    {
+        name: "cross_repo_refs",
+        category: "cross-repo",
+        searchHint: "cross-repo references symbol across all repositories",
+        description: "Find references to a symbol across ALL indexed repositories.",
+        schema: {
+            symbol_name: z.string().describe("Symbol name to find references for"),
+            repo_pattern: z.string().optional().describe("Filter repos by name pattern"),
+            file_pattern: z.string().optional().describe("Filter files by glob pattern"),
+        },
+        handler: (args) => crossRepoFindReferences(args.symbol_name, {
+            repo_pattern: args.repo_pattern,
+            file_pattern: args.file_pattern,
+        }),
+    },
+    // --- Patterns ---
+    {
+        name: "search_patterns",
+        category: "patterns",
+        searchHint: "search patterns anti-patterns CQ violations useEffect empty-catch console-log",
+        description: "Search structural patterns/anti-patterns. Built-in or custom regex.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            pattern: z.string().describe("Built-in pattern name or custom regex"),
+            file_pattern: z.string().optional().describe("Filter to files matching this path substring"),
+            include_tests: zBool().describe("Include test files (default: false)"),
+            max_results: zNum().describe("Max results (default: 50)"),
+        },
+        handler: async (args) => {
+            const result = await searchPatterns(args.repo, args.pattern, {
+                file_pattern: args.file_pattern,
+                include_tests: args.include_tests,
+                max_results: args.max_results,
+            });
+            return formatSearchPatterns(result);
+        },
+    },
+    {
+        name: "list_patterns",
+        category: "patterns",
+        searchHint: "list available built-in patterns anti-patterns",
+        description: "List all available built-in structural code patterns for search_patterns.",
+        schema: {},
+        handler: async () => listPatterns(),
+    },
+    // --- Report ---
+    {
+        name: "generate_report",
+        category: "reporting",
+        searchHint: "generate HTML report complexity dead code hotspots architecture browser",
+        description: "Generate a standalone HTML report with complexity, dead code, hotspots, and architecture. Opens in any browser.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+        },
+        handler: (args) => generateReport(args.repo),
+    },
+    // --- Conversations ---
+    {
+        name: "index_conversations",
+        category: "conversations",
+        searchHint: "index conversations Claude Code history JSONL",
+        description: "Index Claude Code conversation history for search. Scans JSONL files in ~/.claude/projects/ for the given project path.",
+        schema: {
+            project_path: z.string().optional().describe("Path to the Claude project conversations directory. Auto-detects from cwd if omitted."),
+            quiet: zBool().describe("Suppress output (used by session-end hook)"),
+        },
+        handler: async (args) => indexConversations(args.project_path),
+    },
+    {
+        name: "search_conversations",
+        category: "conversations",
+        searchHint: "search conversations past sessions history BM25 semantic",
+        description: "Search conversations in one project (BM25+semantic). For all projects: search_all_conversations.",
+        schema: {
+            query: z.string().describe("Search query — keywords or natural language"),
+            project: z.string().optional().describe("Project path to search (default: current project)"),
+            limit: zNum().optional().describe("Maximum results to return (default: 10, max: 50)"),
+        },
+        handler: async (args) => {
+            const result = await searchConversations(args.query, args.project, args.limit);
+            return formatConversations(result);
+        },
+    },
+    {
+        name: "find_conversations_for_symbol",
+        category: "conversations",
+        searchHint: "find conversations symbol discussion cross-reference code",
+        description: "Find conversations that discussed a code symbol. Cross-refs code + history.",
+        schema: {
+            symbol_name: z.string().describe("Name of the code symbol to search for in conversations"),
+            repo: z.string().describe("Code repository to resolve the symbol from (e.g., 'local/my-project')"),
+            limit: zNum().optional().describe("Maximum conversation results (default: 5)"),
+        },
+        handler: async (args) => {
+            const result = await findConversationsForSymbol(args.symbol_name, args.repo, args.limit);
+            return formatConversations(result);
+        },
+    },
+    {
+        name: "search_all_conversations",
+        category: "conversations",
+        searchHint: "search all conversations every project cross-project",
+        description: "Search ALL conversation projects at once, ranked by relevance.",
+        schema: {
+            query: z.string().describe("Search query — keywords, natural language, or concept"),
+            limit: zNum().optional().describe("Maximum results across all projects (default: 10)"),
+        },
+        handler: async (args) => {
+            const result = await searchAllConversations(args.query, args.limit);
+            return formatConversations(result);
+        },
+    },
+    // --- Security ---
+    {
+        name: "scan_secrets",
+        category: "security",
+        searchHint: "scan secrets API keys tokens passwords credentials security",
+        outputSchema: OutputSchemas.secrets,
+        description: "Scan for hardcoded secrets (API keys, tokens, passwords). ~1,100 rules.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            file_pattern: z.string().optional().describe("Glob pattern to filter scanned files"),
+            min_confidence: z.enum(["high", "medium", "low"]).optional().describe("Minimum confidence level (default: medium)"),
+            exclude_tests: zBool().describe("Exclude test file findings (default: true)"),
+            severity: z.enum(["critical", "high", "medium", "low"]).optional().describe("Minimum severity level"),
+        },
+        handler: async (args) => {
+            const result = await scanSecrets(args.repo, {
+                file_pattern: args.file_pattern,
+                min_confidence: args.min_confidence,
+                exclude_tests: args.exclude_tests,
+                severity: args.severity,
+            });
+            return formatSecrets(result);
+        },
+    },
+    // --- Memory consolidation ---
+    {
+        name: "consolidate_memories",
+        category: "conversations",
+        searchHint: "consolidate memories dream knowledge MEMORY.md decisions solutions patterns",
+        description: "Consolidate conversations into MEMORY.md — decisions, solutions, patterns.",
+        schema: {
+            project_path: z.string().optional().describe("Project path (auto-detects from cwd if omitted)"),
+            output_path: z.string().optional().describe("Custom output file path (default: MEMORY.md in project root)"),
+            min_confidence: z.enum(["high", "medium", "low"]).optional().describe("Minimum confidence level for extracted memories (default: low)"),
+        },
+        handler: async (args) => {
+            const opts = {};
+            if (typeof args.output_path === "string")
+                opts.output_path = args.output_path;
+            if (typeof args.min_confidence === "string")
+                opts.min_confidence = args.min_confidence;
+            const result = await consolidateMemories(args.project_path, opts);
+            return result;
+        },
+    },
+    {
+        name: "read_memory",
+        category: "conversations",
+        searchHint: "read memory MEMORY.md institutional knowledge past decisions",
+        description: "Read MEMORY.md knowledge file with past decisions and patterns.",
+        schema: {
+            project_path: z.string().optional().describe("Project path (default: current directory)"),
+        },
+        handler: async (args) => {
+            const result = await readMemory(args.project_path);
+            if (!result)
+                return { error: "No MEMORY.md found. Run consolidate_memories first." };
+            return result.content;
+        },
+    },
+    // --- Coordinator ---
+    {
+        name: "create_analysis_plan",
+        category: "meta",
+        searchHint: "create plan multi-step analysis workflow coordinator scratchpad",
+        description: "Create multi-step analysis plan with shared scratchpad and dependencies.",
+        schema: {
+            title: z.string().describe("Plan title describing the analysis goal"),
+            steps: z.union([
+                z.array(z.object({
+                    description: z.string(),
+                    tool: z.string(),
+                    args: z.record(z.string(), z.unknown()),
+                    result_key: z.string().optional(),
+                    depends_on: z.array(z.string()).optional(),
+                })),
+                z.string().transform((s) => JSON.parse(s)),
+            ]).describe("Steps array: {description, tool, args, result_key?, depends_on?}. JSON string OK."),
+        },
+        handler: async (args) => {
+            const result = await createAnalysisPlan(args.title, args.steps);
+            return result;
+        },
+    },
+    {
+        name: "scratchpad_write",
+        category: "meta",
+        searchHint: "scratchpad write store knowledge cross-step data persist",
+        description: "Write key-value to plan scratchpad for cross-step knowledge sharing.",
+        schema: {
+            plan_id: z.string().describe("Analysis plan identifier"),
+            key: z.string().describe("Key name for the entry"),
+            value: z.string().describe("Value to store"),
+        },
+        handler: async (args) => writeScratchpad(args.plan_id, args.key, args.value),
+    },
+    {
+        name: "scratchpad_read",
+        category: "meta",
+        searchHint: "scratchpad read retrieve knowledge entry",
+        description: "Read a key from a plan's scratchpad. Returns the stored value or null if not found.",
+        schema: {
+            plan_id: z.string().describe("Analysis plan identifier"),
+            key: z.string().describe("Key name to read"),
+        },
+        handler: async (args) => {
+            const result = await readScratchpad(args.plan_id, args.key);
+            return result ?? { error: "Key not found in scratchpad" };
+        },
+    },
+    {
+        name: "scratchpad_list",
+        category: "meta",
+        searchHint: "scratchpad list entries keys",
+        description: "List all entries in a plan's scratchpad with their sizes.",
+        schema: {
+            plan_id: z.string().describe("Analysis plan identifier"),
+        },
+        handler: (args) => listScratchpad(args.plan_id),
+    },
+    {
+        name: "update_step_status",
+        category: "meta",
+        searchHint: "update step status plan progress completed failed",
+        description: "Update step status in plan. Auto-updates plan status on completion.",
+        schema: {
+            plan_id: z.string().describe("Analysis plan identifier"),
+            step_id: z.string().describe("Step identifier (e.g. step_1)"),
+            status: z.enum(["pending", "in_progress", "completed", "failed", "skipped"]).describe("New status for the step"),
+            error: z.string().optional().describe("Error message if status is 'failed'"),
+        },
+        handler: async (args) => {
+            const result = await updateStepStatus(args.plan_id, args.step_id, args.status, args.error);
+            return result;
+        },
+    },
+    {
+        name: "get_analysis_plan",
+        category: "meta",
+        searchHint: "get plan status steps progress",
+        description: "Get the current state of an analysis plan including all step statuses.",
+        schema: {
+            plan_id: z.string().describe("Analysis plan identifier"),
+        },
+        handler: async (args) => {
+            const plan = getPlan(args.plan_id);
+            return plan ?? { error: "Plan not found" };
+        },
+    },
+    {
+        name: "list_analysis_plans",
+        category: "meta",
+        searchHint: "list plans active analysis workflows",
+        description: "List all active analysis plans with their completion status.",
+        schema: {},
+        handler: async () => listPlans(),
+    },
+    // --- Review diff ---
+    {
+        name: "review_diff",
+        category: "diff",
+        searchHint: "review diff static analysis git changes secrets breaking-changes complexity dead-code blast-radius",
+        description: "Run 9 parallel static analysis checks on a git diff: secrets, breaking changes, coupling gaps, complexity, dead-code, blast-radius, bug-patterns, test-gaps, hotspots. Returns a scored verdict (pass/warn/fail) with tiered findings.",
+        schema: {
+            repo: z.string().describe("Repository identifier"),
+            since: z.string().optional().describe("Base git ref (default: HEAD~1)"),
+            until: z.string().optional().describe("Target ref. Default: HEAD. Special: WORKING, STAGED"),
+            checks: z.string().optional().describe("Comma-separated check names (default: all)"),
+            exclude_patterns: z.string().optional().describe("Comma-separated globs to exclude"),
+            token_budget: zNum().describe("Max tokens (default: 15000)"),
+            max_files: zNum().describe("Warn above N files (default: 50)"),
+            check_timeout_ms: zNum().describe("Per-check timeout ms (default: 8000)"),
+        },
+        handler: async (args) => {
+            const checksArr = args.checks
+                ? args.checks.split(",").map((c) => c.trim()).filter(Boolean)
+                : undefined;
+            const excludeArr = args.exclude_patterns
+                ? args.exclude_patterns.split(",").map((p) => p.trim()).filter(Boolean)
+                : undefined;
+            const opts = {
+                repo: args.repo,
+            };
+            if (args.since != null)
+                opts.since = args.since;
+            if (args.until != null)
+                opts.until = args.until;
+            if (checksArr != null)
+                opts.checks = checksArr.join(",");
+            if (excludeArr != null)
+                opts.exclude_patterns = excludeArr;
+            if (args.token_budget != null)
+                opts.token_budget = args.token_budget;
+            if (args.max_files != null)
+                opts.max_files = args.max_files;
+            if (args.check_timeout_ms != null)
+                opts.check_timeout_ms = args.check_timeout_ms;
+            const result = await reviewDiff(args.repo, opts);
+            return formatReviewDiff(result);
+        },
+    },
+    // --- Stats ---
+    {
+        name: "usage_stats",
+        category: "meta",
+        searchHint: "usage statistics tool calls tokens timing metrics",
+        outputSchema: OutputSchemas.usageStats,
+        description: "Show usage statistics for all CodeSift tool calls (call counts, tokens, timing, repos)",
+        schema: {},
+        handler: async () => {
+            const stats = await getUsageStats();
+            return { report: formatUsageReport(stats) };
+        },
+    },
+];
+function buildToolSummaries() {
+    return TOOL_DEFINITIONS.map((t) => ({
+        name: t.name,
+        category: t.category,
+        description: t.description,
+        searchHint: t.searchHint,
+    }));
+}
+/**
+ * Extract structured param info from a ToolDefinition's Zod schema.
+ */
+function extractToolParams(def) {
+    return Object.entries(def.schema).map(([key, val]) => {
+        const zodVal = val;
+        const isOptional = zodVal.isOptional?.() ?? false;
+        return {
+            name: key,
+            required: !isOptional,
+            description: zodVal.description ?? "",
+        };
+    });
+}
+/**
+ * Return full param details for a specific list of tool names.
+ * Unknown names are collected in not_found.
+ */
+export function describeTools(names) {
+    const capped = names.slice(0, 100); // CQ6 cap
+    const tools = [];
+    const not_found = [];
+    for (const name of capped) {
+        const def = TOOL_DEFINITIONS.find((t) => t.name === name);
+        if (!def) {
+            not_found.push(name);
+            continue;
+        }
+        tools.push({
+            name: def.name,
+            category: def.category ?? "uncategorized",
+            description: def.description,
+            is_core: CORE_TOOL_NAMES.has(def.name),
+            params: extractToolParams(def),
+        });
+    }
+    return { tools, not_found };
+}
+/**
+ * Search tool catalog by keyword. Returns matching tools with descriptions.
+ * Uses simple token matching against name + description + searchHint + category.
+ */
+export function discoverTools(query, category) {
+    const summaries = buildToolSummaries();
+    const queryTokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const categories = [...new Set(summaries.map((s) => s.category).filter(Boolean))];
+    let filtered = summaries;
+    if (category) {
+        filtered = filtered.filter((s) => s.category === category);
+    }
+    // Score each tool by keyword match
+    const scored = filtered.map((tool) => {
+        const searchable = `${tool.name} ${tool.description} ${tool.searchHint ?? ""} ${tool.category ?? ""}`.toLowerCase();
+        let score = 0;
+        for (const token of queryTokens) {
+            if (searchable.includes(token))
+                score++;
+            // Bonus for name match
+            if (tool.name.includes(token))
+                score += 2;
+        }
+        // If no query tokens, match everything (category-only filter)
+        if (queryTokens.length === 0)
+            score = 1;
+        return { tool, score };
+    });
+    const matches = scored
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 15)
+        .map((s) => {
+        // Look up full definition to extract param info for deferred tools
+        const fullDef = TOOL_DEFINITIONS.find((t) => t.name === s.tool.name);
+        const params = fullDef
+            ? extractToolParams(fullDef).map((p) => `${p.name}${p.required ? "" : "?"}: ${p.description || "string"}`)
+            : [];
+        return {
+            name: s.tool.name,
+            category: s.tool.category ?? "uncategorized",
+            description: s.tool.description.slice(0, 200),
+            params: params.length > 0 ? params : undefined,
+            is_core: CORE_TOOL_NAMES.has(s.tool.name),
+        };
+    });
+    return {
+        query,
+        matches,
+        total_tools: TOOL_DEFINITIONS.length,
+        categories,
+    };
+}
+// ---------------------------------------------------------------------------
+// Registration loop
+// ---------------------------------------------------------------------------
+export function registerTools(server, options) {
+    const deferNonCore = options?.deferNonCore ?? false;
+    // Clear handles from any previous registration (e.g. tests calling registerTools multiple times)
+    toolHandles.clear();
+    // Register ALL tools with full schema; store returned handles
+    for (const tool of TOOL_DEFINITIONS) {
+        const handle = server.tool(tool.name, tool.description, tool.schema, async (args) => wrapTool(tool.name, args, () => tool.handler(args))());
+        toolHandles.set(tool.name, handle);
+    }
+    // Always register discover_tools meta-tool
+    const discoverHandle = server.tool("discover_tools", "Search tool catalog by keyword or category. Returns matching tools with descriptions.", {
+        query: z.string().describe("Keywords to search for (e.g. 'dead code', 'complexity', 'rename', 'secrets')"),
+        category: z.string().optional().describe("Filter by category (e.g. 'analysis', 'lsp', 'architecture')"),
+    }, async (args) => wrapTool("discover_tools", args, async () => {
+        return discoverTools(args.query, args.category);
+    })());
+    toolHandles.set("discover_tools", discoverHandle);
+    // Register describe_tools meta-tool — returns full schema for specific tools by name
+    const describeHandle = server.tool("describe_tools", "Get full schema for specific tools by name. Use after discover_tools to see params before calling.", {
+        names: z.array(z.string()).describe("Tool names to describe"),
+        reveal: zBool().describe("If true, enable tools in ListTools so the LLM can call them"),
+    }, async (args) => wrapTool("describe_tools", args, async () => {
+        const result = describeTools(args.names);
+        if (args.reveal === true) {
+            for (const t of result.tools) {
+                const h = toolHandles.get(t.name);
+                if (h)
+                    h.enable();
+            }
+        }
+        return result;
+    })());
+    toolHandles.set("describe_tools", describeHandle);
+    // In deferred mode, disable non-core tools (they remain registered but hidden from ListTools).
+    // LLM discovers them via discover_tools, then reveals with describe_tools(reveal: true).
+    if (deferNonCore) {
+        for (const [name, handle] of toolHandles) {
+            if (!CORE_TOOL_NAMES.has(name) && name !== "discover_tools" && name !== "describe_tools") {
+                handle.disable();
+            }
+        }
+    }
+    // Register progressive shorteners for analysis tools with large outputs
+    registerShortener("analyze_complexity", { compact: formatComplexityCompact, counts: formatComplexityCounts });
+    registerShortener("find_clones", { compact: formatClonesCompact, counts: formatClonesCounts });
+    registerShortener("analyze_hotspots", { compact: formatHotspotsCompact, counts: formatHotspotsCounts });
+}
+//# sourceMappingURL=register-tools.js.map