@pkgseer/cli 0.4.7 → 0.4.8

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-z0xepgqq.js";
+} from "./shared/chunk-edcjw6wf.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -5117,16 +5117,39 @@ async function setupCodexViaCli(shellService) {
 }
 function showAvailableTools(hasProject, useColors) {
   console.log(`
-Available MCP tools:`);
-  console.log("  • package_summary - Get package overview");
-  console.log("  • package_vulnerabilities - Check for security issues");
-  console.log("  • package_quality - Get quality score");
-  console.log("  • package_dependencies - List dependencies");
-  console.log("  • compare_packages - Compare multiple packages");
-  console.log("  • list_package_docs - List documentation pages");
-  console.log("  • fetch_package_doc - Fetch documentation content");
-  console.log("  • search_package_docs - Search package documentation");
-  console.log("  • search_project_docs - Search docs across project dependencies");
+Available MCP tools (21):`);
+  console.log("");
+  console.log("  Navigate source:");
+  console.log("    • find_symbol - Read source code of functions/classes");
+  console.log("    • list_symbols - Browse public API or file symbols");
+  console.log("    • search_symbols - Full-text search within package code");
+  console.log("    • symbol_callers - Trace what calls a function");
+  console.log("    • symbol_callees - Trace what a function calls");
+  console.log("    • call_path - Find call path between two functions");
+  console.log("");
+  console.log("  Browse files:");
+  console.log("    • list_repo_files - Explore package file structure");
+  console.log("    • grep_repo_file - Search for patterns in source files");
+  console.log("    • fetch_code_context - Read source by file path and line range");
+  console.log("");
+  console.log("  Search & docs:");
+  console.log("    • search - Search code and docs across packages");
+  console.log("    • search_project_docs - Search docs across project dependencies");
+  console.log("    • list_package_docs - List documentation pages");
+  console.log("    • fetch_package_doc - Fetch documentation content");
+  console.log("");
+  console.log("  Evaluate:");
+  console.log("    • package_summary - Get package overview");
+  console.log("    • package_quality - Get quality score");
+  console.log("    • package_vulnerabilities - Check for security issues");
+  console.log("    • compare_packages - Compare multiple packages");
+  console.log("    • package_dependencies - List dependencies");
+  console.log("    • version_diff - Compare changes between versions");
+  console.log("");
+  console.log("  Utility:");
+  console.log("    • trigger_indexing - Pre-warm package indexes");
+  console.log("    • search_status - Check async search progress");
+  console.log("    • package_imports - See what a package imports");
   if (!hasProject) {
     console.log(dim(`
 Tip: Create pkgseer.yml to enable automatic project detection for search_project_docs.`, useColors));
@@ -6022,27 +6045,51 @@ function generateSkillContent(invocation = "pkgseer") {
   return `---
 name: pkgseer
 version: ${version}
-description: Search code/docs across npm, PyPI, Hex packages. Provides quality scores, security vulnerabilities, dependencies, comparisons. Use when user asks about package security, CVEs, vulnerabilities, code examples, API usage, package comparison, dependency analysis, or which package to use.
+description: Navigate source code, trace call graphs, and search docs across npm/PyPI/Hex packages. Quality scores, vulnerability checks, dependency analysis, and cross-package comparison. Use when debugging third-party dependencies, understanding how a library works internally, tracing a stack trace into dependency code, evaluating or comparing packages, checking security vulnerabilities, or understanding what changed between versions.
 ---
 
-# PkgSeer - Package Intelligence
+# PkgSeer - Package Source Code & Intelligence
 
-Search and analyze packages across npm, PyPI, and Hex. All commands support \`--json\`.
+Navigate dependency source code and analyze packages across npm, PyPI, and Hex. All commands support \`--json\`.
 
-## Search (Primary Use Case)
+Use PkgSeer instead of guessing library behavior, cloning repos, or browsing GitHub.
+
+## Code Navigation (Debug & Understand Dependencies)
+
+\`\`\`bash
+# Read source code of a function/class — use instead of guessing from training data
+${invocation} code find express Router --include-code
+${invocation} code find pypi:requests Session --include-code
+
+# Trace what calls a function (find entry points, debug triggers)
+${invocation} code callers -r npm -p express -n Router
+
+# Trace what a function calls (follow execution path)
+${invocation} code callees -r npm -p express -n Router
+
+# Find how function A reaches function B
+${invocation} code path -r npm -p express --from-name listen --to-name createServer
+
+# Search for error messages or patterns in dependency source
+${invocation} code search express "ERR_HTTP_HEADERS_SENT"
+${invocation} code grep express src/router/index.js "handle"
+
+# Browse package structure, API, and imports
+${invocation} code files express --path-prefix src/
+${invocation} code list express --scope exports
+${invocation} code imports express --resolved-only
+
+# Compare versions (detect breaking changes after upgrades)
+${invocation} code diff express v4.18.2 v5.0.0
+\`\`\`
+
+## Search Across Packages
 
 \`\`\`bash
-# Search code and docs across packages
 ${invocation} search "<query>" -P lodash,express         # npm packages
 ${invocation} search "<query>" -P pypi:requests          # PyPI packages
-${invocation} search "authentication" -P hex:phoenix,hex:plug
-
-# Search modes
 ${invocation} search "<query>" -P <packages> --mode code  # Code only
 ${invocation} search "<query>" -P <packages> --mode docs  # Docs only
-
-# Docs-only search (shorthand)
-${invocation} docs search "<query>" -P <packages>
 \`\`\`
 
 ## Package Analysis
@@ -6050,23 +6097,11 @@ ${invocation} docs search "<query>" -P <packages>
 Package format: \`[registry:]name[@version]\`
 
 \`\`\`bash
-# Overview: metadata, versions, quickstart
-${invocation} pkg info lodash
-${invocation} pkg info pypi:requests
-
-# Quality score (0-100) with category breakdown
-${invocation} pkg quality express@4.18.0
-${invocation} pkg quality pypi:django@4.2
-
-# Security: CVEs, severity, upgrade paths
-${invocation} pkg vulns lodash@4.17.21
-
-# Dependencies: direct, transitive, tree view
-${invocation} pkg deps express --transitive
-
-# Compare up to 10 packages
-${invocation} pkg compare lodash underscore ramda
-${invocation} pkg compare axios pypi:httpx  # cross-registry
+${invocation} pkg info lodash                        # Overview, versions, quickstart
+${invocation} pkg quality express@4.18.0             # Quality score (0-100)
+${invocation} pkg vulns lodash@4.17.21               # CVEs, severity, upgrade paths
+${invocation} pkg deps express --transitive          # Dependency tree
+${invocation} pkg compare lodash underscore ramda    # Side-by-side comparison
 \`\`\`
 
 ## Documentation
@@ -6082,6 +6117,7 @@ ${invocation} docs search "<query>" -P <packages> # Search docs only
 - Package format: \`[registry:]name[@version]\` (e.g., \`pypi:django@4.2\`)
 - Default registry: npm
 - Use \`--json\` for structured output when parsing
+- Quick start: \`${invocation} code find <package> <function> --include-code\`
 `;
 }
 function extractSkillVersion(content) {
@@ -6214,7 +6250,8 @@ PkgSeer skill ${action} for ${toolName}!`, useColors));
   console.log(`Location: ${highlight(paths.skillPath, useColors)}`);
   console.log(dim(`
 The skill is now available. Try asking:
-` + `  "Search for authentication examples in express"
+` + `  "How does express Router work internally?"
+` + `  "What changed between express v4 and v5?"
 ` + `  "Is lodash secure? Check for vulnerabilities"
 ` + '  "Compare axios vs fetch vs got"', useColors));
 }
@@ -6828,8 +6865,9 @@ var argsSchema = {
 function createCallPathTool(pkgseerService) {
   return {
     name: "call_path",
-    description: "Find the shortest call path between two symbols in the same package. " + "Uses BFS to trace how function A eventually calls function B through intermediate calls. " + "Returns whether a path was found, with ordered call paths (shortest first) and hop details. " + "For direct callers/callees only, use symbol_callers or symbol_callees instead.",
+    description: "Trace how execution flows from one function to another in a dependency — " + "debug how a public API reaches an internal function or error handler. " + "Uses BFS through intermediate calls. " + "Returns ordered call paths (shortest first) with hop details. " + "For direct callers/callees only, use symbol_callers or symbol_callees instead.",
     schema: argsSchema,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find call path", async () => {
         const fromInput = toSymbolReferenceInput(args.from);
@@ -6871,6 +6909,7 @@ function createComparePackagesTool(pkgseerService) {
     name: "compare_packages",
     description: "Compare 2-10 packages side-by-side. Use this when evaluating alternatives (e.g., react vs preact vs solid-js). " + "Returns for each package: quality score, download counts, vulnerability count, license, and latest version. " + "Supports cross-registry comparison (npm, pypi, hex, crates). " + 'Format: [{"registry":"npm","name":"lodash"},{"registry":"npm","name":"underscore"}]',
     schema: argsSchema2,
+    annotations: { readOnlyHint: true },
     handler: async ({ packages }, _extra) => {
       return withErrorHandling("compare packages", async () => {
         const input2 = packages.map((pkg) => ({
@@ -6902,8 +6941,9 @@ var argsSchema3 = {
 function createFetchCodeContextTool(pkgseerService) {
   return {
     name: "fetch_code_context",
-    description: "Fetch code content from a repository by file path and line range. " + "Returns full file by default, or a specific line range. " + "For symbol-based lookup, use find_symbol(include_code=true) instead. " + "Requires repo_url, git_ref (tag/commit/branch), and file_path.",
+    description: "Read source code from a dependency's repository by file path and line range — " + "use when you have a file path from a stack trace or symbol lookup. " + "Returns full file or a specific line range. " + "Prefer find_symbol(include_code=true) for function/class lookup. " + "Requires repo_url, git_ref, and file_path.",
     schema: argsSchema3,
+    annotations: { readOnlyHint: true },
     handler: async ({ repo_url, git_ref, file_path, start_line, end_line }, _extra) => {
       return withErrorHandling("fetch code context", async () => {
         const result = await pkgseerService.fetchCodeContext(repo_url, git_ref, file_path, {
@@ -6931,6 +6971,7 @@ function createFetchPackageDocTool(pkgseerService) {
     name: "fetch_package_doc",
     description: "Get full content of a documentation page. Requires page_id from list_package_docs. " + "Returns: title, full content (markdown/HTML), format type, navigation breadcrumbs, " + "source URL, and last updated timestamp. Use this when you need complete documentation, " + "not just search snippets.",
     schema: argsSchema4,
+    annotations: { readOnlyHint: true },
     handler: async ({ page_id }, _extra) => {
       return withErrorHandling("fetch documentation page", async () => {
         const result = await pkgseerService.getDocPage(page_id);
@@ -6971,8 +7012,9 @@ var argsSchema5 = {
 function createFindSymbolTool(pkgseerService) {
   return {
     name: "find_symbol",
-    description: "Find functions, methods, or classes by name in a package. " + "Set include_code=true to get full source code inline, avoiding separate fetch_code_context calls. " + "Returns: symbol ref, name, qualified path, kind, file location, and optionally source code. " + "Omit name to get all public exports. Use namespace to filter by module path.",
+    description: "Read source code of any function, class, or method in a third-party package — " + "use instead of guessing implementations from training data. " + "Set include_code=true for full source inline. " + "Returns: symbol ref, name, qualified path, kind, file location, and optionally source code. " + "Omit name to get all public exports. Use namespace to filter by module path.",
     schema: argsSchema5,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol", async () => {
         const result = await pkgseerService.findSymbol(toGraphQLRegistry(args.registry), args.package_name, {
@@ -7016,8 +7058,9 @@ var argsSchema6 = {
 function createGrepRepoFileTool(pkgseerService) {
   return {
     name: "grep_repo_file",
-    description: "Search for a pattern within a file in a package's repository. " + "Case-insensitive substring matching. Returns matching lines with context. " + "Faster than fetch_code_context for large files. " + "Use list_repo_files to discover available file paths.",
+    description: "Search for a pattern within a dependency's source file — " + "find error messages, config keys, or specific patterns without cloning the repo. " + "Case-insensitive substring matching with context lines. " + "Faster than fetch_code_context for large files. " + "Use list_repo_files to discover file paths.",
     schema: argsSchema6,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("grep repo file", async () => {
         const result = await pkgseerService.grepRepoFile(toGraphQLRegistry(args.registry), args.package_name, args.file_path, args.pattern, {
@@ -7050,8 +7093,9 @@ var argsSchema7 = {
 function createListPackageDocsTool(pkgseerService) {
   return {
     name: "list_package_docs",
-    description: "Discover available documentation pages for a package. Start here before fetching or searching docs. " + "Returns: page titles, unique IDs (needed for fetch_package_doc), word counts, and update timestamps. " + "Workflow: list_package_docs → fetch_package_doc for full content, or search_package_docs to find specific topics.",
+    description: "Discover available documentation pages for a package. Start here before fetching or searching docs. " + "Returns: page titles, unique IDs (needed for fetch_package_doc), word counts, and update timestamps. " + "Workflow: list_package_docs → fetch_package_doc for full content, or search(mode='docs') to find specific topics.",
     schema: argsSchema7,
+    annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("list package documentation", async () => {
         const result = await pkgseerService.listPackageDocs(toGraphQLRegistry(registry), package_name, version2);
@@ -7079,8 +7123,9 @@ var argsSchema8 = {
 function createListRepoFilesTool(pkgseerService) {
   return {
     name: "list_repo_files",
-    description: "List files in a package's indexed repository. " + "Returns file paths, names, languages, types (source/doc/config), and sizes. " + "Use path_prefix to filter by directory (e.g., 'src/'). " + "Useful for exploring package structure before searching or reading code.",
+    description: "Explore a dependency's file structure — " + "see what source files, configs, and docs exist. " + "Returns file paths, names, languages, types (source/doc/config), and sizes. " + "Use path_prefix to filter by directory (e.g., 'src/'). " + "Good first step when investigating unfamiliar package internals.",
     schema: argsSchema8,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("list repo files", async () => {
         const result = await pkgseerService.listRepoFiles(toGraphQLRegistry(args.registry), args.package_name, {
@@ -7122,8 +7167,9 @@ var argsSchema9 = {
 function createListSymbolsTool(pkgseerService) {
   return {
     name: "list_symbols",
-    description: "Browse symbols in a package by scope. " + "Use scope='exports' for public API with namespace grouping and optional popularity. " + "Use scope='file' with file_path for all symbols in a specific file. " + "Returns symbols with refs, names, qualified paths, kinds, and file locations. " + "Use find_symbol(name=<symbol>, include_code=true) to get source for any listed symbol.",
+    description: "Browse a dependency's public API or file-level symbols. " + "Use scope='exports' for the public API with optional popularity ranking. " + "Use scope='file' with file_path for all symbols in a specific file. " + "Returns symbol refs, names, qualified paths, kinds, and file locations. " + "Use find_symbol(name=<symbol>, include_code=true) to read source for any result.",
     schema: argsSchema9,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("list symbols", async () => {
         const scope = toListScope(args.scope);
@@ -7245,6 +7291,7 @@ function createPackageDependenciesTool(pkgseerService) {
     name: "package_dependencies",
     description: "Analyze package dependencies. By default returns direct dependencies only. " + "Set include_transitive=true to get the full dependency tree (use max_depth to limit large trees). " + "Returns: dependency names, version constraints, and for transitive deps, a graph with depth levels. " + "Use this to understand complexity before adding a package, or to find nested dependencies.",
     schema: argsSchema10,
+    annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2, include_transitive, max_depth }, _extra) => {
       return withErrorHandling("fetch package dependencies", async () => {
         const result = await pkgseerService.getPackageDependencies(toGraphQLRegistry(registry), package_name, version2, include_transitive, max_depth);
@@ -7296,8 +7343,9 @@ var argsSchema11 = {
 function createPackageImportsTool(pkgseerService) {
   return {
     name: "package_imports",
-    description: "Get import statements in a package. " + "Returns parsed import/require/use statements with optional resolution to known packages. " + "Use resolved_only=true to see only imports that map to packages in the PkgSeer registry. " + "Includes: source path, imported names, and de-duplicated dependency list.",
+    description: "See what a dependency imports — understand its internal dependencies and external package usage. " + "Returns parsed import/require/use statements with optional resolution to known packages. " + "Use resolved_only=true to see only imports that map to packages in the PkgSeer registry. " + "Includes: source path, imported names, and de-duplicated dependency list.",
     schema: argsSchema11,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("fetch package imports", async () => {
         const result = await pkgseerService.packageImports(toGraphQLRegistry(args.registry), args.package_name, {
@@ -7330,6 +7378,7 @@ function createPackageQualityTool(pkgseerService) {
     name: "package_quality",
     description: "Evaluate package maintenance health and code quality. Use this to assess if a package is well-maintained " + "before adding it as a dependency. Returns: overall score (0-100), category scores (documentation, " + "testing, community, maintenance), and individual rule results with pass/fail status. " + "Useful for comparing quality between alternative packages.",
     schema: argsSchema12,
+    annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package quality", async () => {
         const result = await pkgseerService.getPackageQuality(toGraphQLRegistry(registry), package_name, version2);
@@ -7354,6 +7403,7 @@ function createPackageSummaryTool(pkgseerService) {
     name: "package_summary",
     description: "Get a comprehensive overview of a package. Use this as your first tool when researching a package. " + "Returns: description, latest version, license, repository URL, download stats, " + "active security advisories count, and quickstart/installation instructions. " + "For deeper analysis, follow up with package_quality (maintenance health) or " + "package_vulnerabilities (security details).",
     schema: argsSchema13,
+    annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name }, _extra) => {
       return withErrorHandling("fetch package summary", async () => {
         const result = await pkgseerService.getPackageSummary(toGraphQLRegistry(registry), package_name);
@@ -7379,6 +7429,7 @@ function createPackageVulnerabilitiesTool(pkgseerService) {
     name: "package_vulnerabilities",
     description: "Check security vulnerabilities for a package. Use this before adding dependencies or when auditing existing ones. " + "Returns: list of CVEs/advisories with severity levels, affected version ranges, fixed versions, " + "and upgrade recommendations. If version is specified, shows only vulnerabilities affecting that version.",
     schema: argsSchema14,
+    annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package vulnerabilities", async () => {
         const result = await pkgseerService.getPackageVulnerabilities(toGraphQLRegistry(registry), package_name, version2);
@@ -7446,6 +7497,7 @@ function createSearchTool(pkgseerService) {
     name: "search",
     description: "Search code and documentation across packages. Returns functions, classes, and doc pages " + "matching your query. Use mode='code' for code only, mode='docs' for docs only, or " + "mode='all' (default). Provide 1-20 packages. Results include relevance scores and snippets. " + "For full source of code results, use find_symbol(name=<title>, include_code=true). " + "If packages need indexing, waits up to waitTimeoutMs (default 10s) or returns searchRef — use search_status to poll.",
     schema: argsSchema15,
+    annotations: { readOnlyHint: true },
     handler: async ({ packages, query, mode, limit, waitTimeoutMs }, _extra) => {
       return withErrorHandling("search packages", async () => {
         const normalizedQuery = query.trim();
@@ -7510,8 +7562,9 @@ function createSearchProjectDocsTool(deps) {
   const { pkgseerService, configService, defaultProjectDir } = deps;
   return {
     name: "search_project_docs",
-    description: "Searches documentation across all dependencies in a PkgSeer project using search terms and match modes (any/all). Returns ranked results from multiple packages. Use project_directory to specify which project's context to use, or project to search a specific project directly.",
+    description: "Search documentation across all dependencies in a PkgSeer project — " + "use when you need to find information but don't know which dependency has it. " + "Requires a pkgseer.yml project config (or pass project name directly). " + "Returns ranked results with snippets from multiple packages. " + "Use project_directory to specify which project's context to use. " + "For single-package doc search, use search(mode='docs') instead.",
     schema: argsSchema16,
+    annotations: { readOnlyHint: true },
     handler: async ({
       project_directory,
       project,
@@ -7566,6 +7619,7 @@ function createSearchStatusTool(pkgseerService) {
     name: "search_status",
     description: "Check the status of an async search and get results if complete. " + "Use after search returns completed=false with a searchRef. Sessions expire after 1 hour. " + "Returns status (PENDING, INDEXING, SEARCHING, COMPLETED, TIMEOUT, FAILED), " + "progress info (packagesReady/packagesTotal), and results when COMPLETED.",
     schema: argsSchema17,
+    annotations: { readOnlyHint: true },
     handler: async ({ searchRef }, _extra) => {
       return withErrorHandling("check search status", async () => {
         const progressResult = await pkgseerService.getSearchProgress(searchRef);
@@ -7631,8 +7685,9 @@ var argsSchema18 = {
 function createSearchSymbolsTool(pkgseerService) {
   return {
     name: "search_symbols",
-    description: "Full-text search within package code. " + "Searches across functions, classes, modules, and doc sections. " + "Supports query string or keyword list with match_mode. " + "Use file_path to filter by directory (e.g., 'src/'). " + "Returns matching code chunks with name, type, file path, line numbers, and content previews. " + "Follow-up: use find_symbol(name=<result.name>, include_code=true) to get full source.",
+    description: "Search a dependency's source code by text — " + "find where error messages, exceptions, or patterns appear across functions, classes, and modules. " + "Supports query string or keyword list with match_mode. " + "Use file_path to filter by directory (e.g., 'src/'). " + "Returns matching code chunks with name, type, file path, line numbers, and content previews. " + "Follow up with find_symbol(name=<result.name>, include_code=true) for full source.",
     schema: argsSchema18,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("search symbols", async () => {
         const result = await pkgseerService.searchSymbols(toGraphQLRegistry(args.registry), args.package_name, {
@@ -7682,8 +7737,9 @@ var argsSchema19 = {
 function createSymbolCalleesTool(pkgseerService) {
   return {
     name: "symbol_callees",
-    description: "Find what a symbol calls (its dependencies). " + "Returns direct callees at max_depth=1, or transitive call chains at higher depths. " + "Includes callee names, qualified paths, file locations, call lines, and external package references. " + "Get symbol_ref from find_symbol or list_symbols results. See symbol_callers for the reverse.",
+    description: "Trace what a function calls internally — " + "understand dependency behavior by following its execution path. " + "Returns direct callees at max_depth=1, or transitive call chains at higher depths. " + "Includes callee names, qualified paths, file locations, call lines, and external package references. " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callers for the reverse.",
     schema: argsSchema19,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callees", async () => {
         const symbolInput = toSymbolReferenceInput(args.symbol);
@@ -7722,8 +7778,9 @@ var argsSchema20 = {
 function createSymbolCallersTool(pkgseerService) {
   return {
     name: "symbol_callers",
-    description: "Find what calls a symbol (its dependents/callers). " + "Returns the target symbol and a list of callers with file locations and call line numbers. " + "Use same_package_only to limit to callers within the same package. " + "Get symbol_ref from find_symbol or list_symbols results. See symbol_callees for the reverse.",
+    description: "Trace what calls a function in a dependency's source code — " + "find entry points or debug why behavior triggers. " + "Returns callers with file locations and call line numbers. " + "Use same_package_only for within-package callers only. " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callees for the reverse.",
     schema: argsSchema20,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callers", async () => {
         const symbolInput = toSymbolReferenceInput(args.symbol);
@@ -7769,6 +7826,7 @@ function createTriggerIndexingTool(pkgseerService) {
     name: "trigger_indexing",
     description: "Pre-warm PkgSeer indexes by triggering indexing for packages and/or repositories. " + "Fire-and-forget: triggers jobs and returns immediately with accepted/skipped counts. " + "Use before search requests to ensure packages are indexed. " + "Rate limited to 10 requests per minute.",
     schema: argsSchema21,
+    annotations: { readOnlyHint: false, idempotentHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("trigger indexing", async () => {
         const packages = args.packages?.map((p) => ({
@@ -7827,8 +7885,9 @@ var argsSchema22 = {
 function createVersionDiffTool(pkgseerService) {
   return {
     name: "version_diff",
-    description: "Compare symbols between two package versions. " + "Detects added, removed, moved, and modified symbols with severity " + "(breaking, behavior_change, non_breaking, internal). " + "Returns summary counts and per-symbol changes with file locations.",
+    description: "Compare two versions of a dependency to understand what changed — " + "use when debugging issues after upgrades or planning migrations. " + "Detects added, removed, moved, and modified symbols with severity " + "(breaking, behavior_change, non_breaking, internal). " + "Returns summary counts and per-symbol changes with file locations.",
     schema: argsSchema22,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("version diff", async () => {
         const result = await pkgseerService.versionDiff(toGraphQLRegistry(args.registry), args.package_name, args.from_version, args.to_version, {
@@ -7849,6 +7908,28 @@ function createVersionDiffTool(pkgseerService) {
   };
 }
 // src/commands/mcp.ts
+var PKGSEER_INSTRUCTIONS = `PkgSeer provides source code intelligence for third-party packages across npm, PyPI, Hex, and other registries. All tools are read-only except trigger_indexing (which only queues background work).
+
+Use PkgSeer when:
+- A stack trace or error originates in a third-party dependency
+- You need to understand how a library function works internally
+- You want to trace call chains through dependency source code
+- You're evaluating, comparing, or auditing packages
+- You need to understand what changed between package versions
+
+Instead of guessing library behavior from training data, use find_symbol(include_code=true) to read actual source.
+Instead of cloning repos to search code, use search_symbols or grep_repo_file.
+Instead of manually tracing call chains on GitHub, use symbol_callers and symbol_callees.
+
+Tool groups:
+- Navigate source: find_symbol, list_symbols, search_symbols, symbol_callers, symbol_callees, call_path
+- Browse files: list_repo_files, grep_repo_file, fetch_code_context
+- Search across packages: search, search_project_docs
+- Browse docs: list_package_docs, fetch_package_doc
+- Evaluate: package_summary, package_quality, package_vulnerabilities, compare_packages, package_dependencies, version_diff
+- Utility: trigger_indexing, search_status, package_imports
+
+Quick start: find_symbol(registry="npm", name="<function>", package_name="<pkg>", include_code=true) often answers the question in one call.`;
 var TOOL_FACTORIES = {
   package_summary: ({ pkgseerService }) => createPackageSummaryTool(pkgseerService),
   package_vulnerabilities: ({ pkgseerService }) => createPackageVulnerabilitiesTool(pkgseerService),
@@ -7904,10 +7985,7 @@ var PROJECT_READ_TOOLS = ["search_project_docs"];
 var ALL_TOOLS = [...PUBLIC_READ_TOOLS, ...PROJECT_READ_TOOLS];
 function createMcpServer(deps) {
   const { pkgseerService, configService, config, fileSystemService } = deps;
-  const server = new McpServer({
-    name: "pkgseer",
-    version: "0.1.0"
-  });
+  const server = new McpServer({ name: "pkgseer", version: "0.1.0" }, { instructions: PKGSEER_INSTRUCTIONS });
   const defaultProjectDir = fileSystemService.getCwd();
   const enabledToolNames = config.enabled_tools ?? ALL_TOOLS;
   const toolsToRegister = enabledToolNames.filter((name) => ALL_TOOLS.includes(name));
@@ -7920,7 +7998,11 @@ function createMcpServer(deps) {
   for (const toolName of toolsToRegister) {
     const factory = TOOL_FACTORIES[toolName];
     const tool = factory(factoryDeps);
-    server.registerTool(tool.name, { description: tool.description, inputSchema: tool.schema }, tool.handler);
+    server.registerTool(tool.name, {
+      description: tool.description,
+      inputSchema: tool.schema,
+      annotations: tool.annotations
+    }, tool.handler);
   }
   return server;
 }
@@ -7969,10 +8051,13 @@ function registerMcpCommand(program) {
 When run interactively (TTY), shows setup instructions.
 When run via stdio (non-TTY), starts the MCP server.
 
-Available tools: package_summary, package_vulnerabilities,
-package_dependencies, package_quality, compare_packages,
-list_package_docs, fetch_package_doc, search_package_docs,
-search_project_docs`).action(async () => {
+Available tools (21):
+  Navigate source: find_symbol, list_symbols, search_symbols, symbol_callers, symbol_callees, call_path
+  Browse files: list_repo_files, grep_repo_file, fetch_code_context
+  Search: search, search_project_docs
+  Docs: list_package_docs, fetch_package_doc
+  Evaluate: package_summary, package_quality, package_vulnerabilities, compare_packages, package_dependencies, version_diff
+  Utility: trigger_indexing, search_status, package_imports`).action(async () => {
     const deps = await createContainer();
     if (process.stdout.isTTY && process.stdin.isTTY) {
       showMcpSetupInstructions(deps);

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./shared/chunk-z0xepgqq.js";
+} from "./shared/chunk-edcjw6wf.js";
 export {
   version
 };

package/dist/shared/{chunk-z0xepgqq.js → chunk-edcjw6wf.js}

@@ -1,4 +1,4 @@
 // package.json
-var version = "0.4.7";
+var version = "0.4.8";
 
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pkgseer/cli",
   "description": "CLI companion for PkgSeer - package intelligence for developers and AI assistants",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "type": "module",
   "files": [
     "dist",