octocode-mcp 2.3.1 → 2.3.4

package/build/index.js

@@ -3,90 +3,48 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { exec } from 'child_process';
 import { promisify } from 'util';
+import { platform } from 'os';
 import NodeCache from 'node-cache';
 import crypto from 'crypto';
 import z from 'zod';
 
-const TOOL_NAMES = {
-    // System & API Status
-    API_STATUS_CHECK: 'api_status_check',
-    // GitHub
-    GITHUB_SEARCH_CODE: 'github_search_code',
-    GITHUB_SEARCH_REPOS: 'github_search_repositories',
-    GITHUB_SEARCH_COMMITS: 'github_search_commits',
-    GITHUB_SEARCH_ISSUES: 'github_search_issues',
-    GITHUB_SEARCH_PULL_REQUESTS: 'github_search_pull_requests',
-    GITHUB_GET_CONTENTS: 'github_get_contents',
-    GITHUB_GET_FILE_CONTENT: 'github_get_file_content',
-    // NPM
-    NPM_PACKAGE_SEARCH: 'npm_package_search',
-    NPM_VIEW_PACKAGE: 'npm_view_package',
-};
-const PROMPT_SYSTEM_PROMPT = `You are a smart code research assistant with semantic search capabilities using gh and npm cli under the hood.
-You are able to search code, repositories, issues, pull requests, commits, and packages.
-Using Github: You are able to search code, repositories, issues, pull requests, commits
-Using NPM: You are able to search packages, view package metadata, and view package dependencies.
+const PROMPT_SYSTEM_PROMPT = `Expert code research assistant for GitHub/NPM ecosystems (public/private). Use powerful semantic search for efficient code discovery.
 
-- ALWAYS START with ${TOOL_NAMES.API_STATUS_CHECK} before evaluating any user query (check npm and GitHub authentication and use GitHub organizations)
-- Understand users query from semantic understanding and choose the right tools for the job.
+CORE TOOLS:
+ GitHub: Code, repos, issues, PRs, commits - supports boolean logic (AND/OR/NOT) and exact phrases
+ NPM: Package search (fuzzy only, no boolean) + metadata (repo URLs, exports, dependencies)
+ API Status: Check connectivity + user's GitHub organizations for private access
 
-TOOLS SEARCH STRATEGY:
-- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} - START SHALLOW & GO BROAD: Use topics for exploratory discovery, then narrow down
-- ${TOOL_NAMES.GITHUB_SEARCH_CODE} - Find implementation patterns with SMART BOOLEAN OPERATORS (AND, OR, NOT)
-- ${TOOL_NAMES.NPM_PACKAGE_SEARCH} - Package ecosystem discovery
-- ${TOOL_NAMES.NPM_VIEW_PACKAGE} - Complete package analysis with exports for file discovery
-- ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} + ${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} - Understanding development patterns
-- ${TOOL_NAMES.GITHUB_GET_CONTENTS} → ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT} - ALWAYS verify file existence before fetching
+SEARCH STRATEGIES:
+GitHub Code/Issues/PRs/Commits:
+ OR (broad): "useState OR setState" - finds alternatives  
+ AND (precise): "react AND hooks" - requires both terms
+ NOT (filter): "auth NOT test" - excludes noise
+ Quotes (exact): "useEffect cleanup" - literal phrases
+ Combine with filters: language, path, owner for focus
 
-BEST PRACTICES:
-- Leverage smart boolean operators if possible in tools and advanced filters for smart research 
-- For repo discovery: START SHALLOW with topics, then go BROAD to explore ecosystems
-- For code search: Be focused and specific with boolean operators
-- Always check documentation and examples when available
-- Add referenced and high quality research data from docs and quality code
-- Be creative and smart and use tools efficiently to gather most data
-- If query is short (e.g. where is the git repo of X package) make simple query and use tools to gather data fast
-- For broad research make steps and think about the best way to gather data`;
-const TOOL_DESCRIPTIONS = {
-    [TOOL_NAMES.API_STATUS_CHECK]: `**MANDATORY FIRST STEP** - Check GitHub & NPM authentication status before any user query evaluation.
-  Returns connectivity status and discovers user organizations - CRITICAL for accessing private/organizational repositories.
-  **DO NOT PROCEED** with searches if both GitHub and NPM are disconnected.
-  **USE ORGANIZATIONS** returned in 'github.organizations' array for targeted owner/org parameters in all search tools.
-  Essential for enterprise code exploration and accessing company-specific repositories that require organizational membership.`,
-    [TOOL_NAMES.NPM_PACKAGE_SEARCH]: `Search NPM packages by keyword. Use for package ecosystem discovery.`,
-    [TOOL_NAMES.NPM_VIEW_PACKAGE]: `Get comprehensive package metadata essential for GitHub searches and code analysis. Returns complete package context:
-  • repositoryGitUrl - Direct GitHub repo link for accurate searches
-  • exports - Critical for discovering available files and import paths  
-  • dependencies/devDependencies - Full ecosystem understanding
-  • versions with dates - Historical evolution context
-  The exports field is invaluable for GitHub file discovery - shows exact paths before fetching. Always use when finding packages in code.`,
-    [TOOL_NAMES.GITHUB_SEARCH_CODE]: `SEMANTIC CODE DISCOVERY: Search code with SMART BOOLEAN OPERATORS (AND, OR, NOT). 
-  Prioritize intelligent boolean combinations: "logger AND debug NOT test", "config OR settings", "error handling AND typescript".
-  Format: "term AND term" language:js path:src. Filters: owner/org/user, repo, extension, filename, language, path, size, limit, match scope. 
-  Use for finding actual implementation patterns and code examples.
-  CRITICAL: When packages found in results or from user input, use ${TOOL_NAMES.NPM_VIEW_PACKAGE} for metadata/paths.`,
-    [TOOL_NAMES.GITHUB_SEARCH_REPOS]: `Search repositories by name/description. START SHALLOW AND GO BROAD (contrary to code search).
-  Use topics for EXPLORATORY discovery: topic:["cli","typescript","api"] to find ecosystem patterns.
-  PRIMARY FILTERS work alone: owner, language, stars, topic, forks. SECONDARY FILTERS require query/primary filter: license, created, archived, includeForks, updated, visibility, match.
-  
-  SMART REPOS SEARCH PATTERNS: Use topic:["cli","typescript"] for semantic discovery. Use stars:">100" for quality. Use owner:"microsoft" for organization repos. Query supports GitHub syntax: "language:Go OR language:Rust".
-  
-  CRITICAL: When finding packages, use ${TOOL_NAMES.NPM_VIEW_PACKAGE} for metadata and repository paths.`,
-    [TOOL_NAMES.GITHUB_GET_CONTENTS]: `Browse repository structure and verify file existence. ALWAYS use before github_get_file_content to confirm files exist and understand organization.`,
-    [TOOL_NAMES.GITHUB_GET_FILE_CONTENT]: `Read file content. REQUIRES exact path verification from github_get_contents first. If fetching fails, check file existence with github_get_contents.`,
-    [TOOL_NAMES.GITHUB_SEARCH_ISSUES]: `Find GitHub issues and problems with rich metadata (labels, reactions, comments, state). 
-  Discover pain points, feature requests, bug patterns, and community discussions. 
-  Filter by state, labels, assignee, or date ranges. Use for understanding project health and common user issues.`,
-    [TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS]: `Find pull requests and implementations with detailed metadata. 
-  Discover how features were implemented, code review patterns, and development workflows. 
-  Filter by state, author, reviewer, or merge status. Essential for understanding project development practices.`,
-    [TOOL_NAMES.GITHUB_SEARCH_COMMITS]: `Search commit history. Use for understanding code evolution and development patterns.`,
-};
+NPM Search:
+ Space-separated keywords only: "react state management"
+ No boolean operators supported
+ Use npm_view_package for direct package metadata → GitHub repo URL
+
+OPTIMIZATION:
+ Check user's GitHub orgs for private repo access
+ npm_view_package gives repo URL instantly - avoid GitHub repo search
+ Use targeted searches, avoid redundant tool calls
+ Combine tools strategically: NPM → GitHub file content
+ Discovery: comprehensive multi-tool approach
+ Direct queries: quick targeted approach
+
+ CLI Help using CLI (use when needed to check failures)
+ gh <command>  --help
+ npm <command> --help
+
+Always provide code snippets and documentation references.`;
 
-// CONSOLIDATED ERROR & SUCCESS HANDLING
 function createResult(data, isError = false, suggestions) {
     const text = isError
-        ? `${data}${suggestions ? ` | Try: ${suggestions.join(', ')}` : ''}`
+        ? `${data}${''}`
         : JSON.stringify(data, null, 2);
     return {
         content: [{ type: 'text', text }],
@@ -110,56 +68,6 @@ function parseJsonResponse(responseText, fallback = null) {
         return { data: (fallback || responseText), parsed: false };
     }
 }
-/**
- * Generate fallback suggestions for no results - ensures no tool suggests itself
- */
-function getNoResultsSuggestions(currentTool) {
-    const suggestions = [];
-    // Tool-specific fallbacks
-    switch (currentTool) {
-        case TOOL_NAMES.GITHUB_SEARCH_REPOS:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_NAMES.NPM_PACKAGE_SEARCH);
-            break;
-        case TOOL_NAMES.GITHUB_SEARCH_CODE:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_REPOS, TOOL_NAMES.GITHUB_SEARCH_ISSUES);
-            break;
-        case TOOL_NAMES.NPM_PACKAGE_SEARCH:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_REPOS, TOOL_NAMES.GITHUB_SEARCH_CODE);
-            break;
-        case TOOL_NAMES.GITHUB_SEARCH_ISSUES:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_NAMES.GITHUB_SEARCH_REPOS);
-            break;
-        case TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_ISSUES, TOOL_NAMES.GITHUB_SEARCH_CODE);
-            break;
-        case TOOL_NAMES.GITHUB_SEARCH_COMMITS:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_NAMES.GITHUB_SEARCH_REPOS);
-            break;
-        case TOOL_NAMES.GITHUB_GET_CONTENTS:
-        case TOOL_NAMES.GITHUB_GET_FILE_CONTENT:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_REPOS, TOOL_NAMES.GITHUB_SEARCH_CODE);
-            break;
-        default:
-            // Fallback for any other tools
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_REPOS, TOOL_NAMES.GITHUB_SEARCH_CODE);
-    }
-    return suggestions.slice(0, 3);
-}
-/**
- * Generate fallback suggestions for errors - ensures no tool suggests itself
- */
-function getErrorSuggestions(currentTool) {
-    const suggestions = [];
-    // Always suggest API status check first (unless it's the current tool)
-    if (currentTool !== TOOL_NAMES.API_STATUS_CHECK) {
-        suggestions.push(TOOL_NAMES.API_STATUS_CHECK);
-    }
-    // Add discovery alternatives
-    if (currentTool !== TOOL_NAMES.GITHUB_SEARCH_REPOS) {
-        suggestions.push(TOOL_NAMES.GITHUB_SEARCH_REPOS);
-    }
-    return suggestions.slice(0, 3);
-}
 /**
  * Determines if a string needs quoting for GitHub search
  */
@@ -229,6 +137,86 @@ function isValidNpmCommand(command) {
 function isValidGhCommand(command) {
     return ALLOWED_GH_COMMANDS.includes(command);
 }
+/**
+ * Get platform-specific shell configuration with PowerShell support
+ */
+function getShellConfig(preferredWindowsShell) {
+    const isWindows = platform() === 'win32';
+    if (!isWindows) {
+        return {
+            shell: '/bin/sh',
+            shellEnv: '/bin/sh',
+            type: 'unix',
+        };
+    }
+    // Windows shell selection
+    const usesPowerShell = preferredWindowsShell === 'powershell';
+    if (usesPowerShell) {
+        return {
+            shell: 'powershell.exe',
+            shellEnv: 'powershell.exe',
+            type: 'powershell',
+        };
+    }
+    return {
+        shell: 'cmd.exe',
+        shellEnv: 'cmd.exe',
+        type: 'cmd',
+    };
+}
+/**
+ * Escape shell arguments to prevent shell injection and handle special characters
+ * Cross-platform compatible escaping for Windows CMD, PowerShell, and Unix shells
+ */
+function escapeShellArg(arg, shellType) {
+    // Auto-detect shell type if not provided
+    if (!shellType) {
+        const isWindows = platform() === 'win32';
+        shellType = isWindows ? 'cmd' : 'unix';
+    }
+    switch (shellType) {
+        case 'powershell':
+            return escapePowerShellArg(arg);
+        case 'cmd':
+            return escapeWindowsCmdArg(arg);
+        case 'unix':
+        default:
+            return escapeUnixShellArg(arg);
+    }
+}
+/**
+ * Escape arguments for PowerShell
+ * PowerShell uses single quotes for literal strings and has special escaping rules
+ */
+function escapePowerShellArg(arg) {
+    // PowerShell special characters that need escaping
+    if (/[\s&<>|;`$@"'()[\]{}]/.test(arg)) {
+        // Use single quotes for literal strings in PowerShell
+        // Escape single quotes by doubling them
+        return `'${arg.replace(/'/g, "''")}'`;
+    }
+    return arg;
+}
+/**
+ * Escape arguments for Windows CMD
+ */
+function escapeWindowsCmdArg(arg) {
+    // Windows CMD escaping
+    if (/[\s&<>|^"]/.test(arg)) {
+        return `"${arg.replace(/"/g, '""')}"`;
+    }
+    return arg;
+}
+/**
+ * Escape arguments for Unix shells (/bin/sh, bash, etc.)
+ */
+function escapeUnixShellArg(arg) {
+    // Unix shell escaping
+    if (/[^\w\-._/:=@]/.test(arg)) {
+        return `'${arg.replace(/'/g, "'\"'\"'")}'`;
+    }
+    return arg;
+}
 /**
  * Execute NPM commands safely by validating against allowed commands
  * Security: Only executes commands that start with "npm {ALLOWED_COMMAND}"
@@ -238,11 +226,18 @@ async function executeNpmCommand(command, args = [], options = {}) {
     if (!isValidNpmCommand(command)) {
         return createErrorResult('Command not registered', new Error(`NPM command '${command}' is not in the allowed list`));
     }
-    // Build command with validated prefix - no sanitization needed since we control the prefix
-    const fullCommand = `npm ${command} ${args.join(' ')}`;
-    const executeNpmCommand = () => executeCommand(fullCommand, 'npm', options);
+    // Get shell configuration
+    const shellConfig = getShellConfig(options.windowsShell);
+    // Build command with validated prefix and properly escaped arguments
+    const escapedArgs = args.map(arg => escapeShellArg(arg, shellConfig.type));
+    const fullCommand = `npm ${command} ${escapedArgs.join(' ')}`;
+    const executeNpmCommand = () => executeCommand(fullCommand, 'npm', options, shellConfig);
     if (options.cache) {
-        const cacheKey = generateCacheKey('npm-exec', { command, args });
+        const cacheKey = generateCacheKey('npm-exec', {
+            command,
+            args,
+            shell: shellConfig.type,
+        });
         return withCache(cacheKey, executeNpmCommand);
     }
     return executeNpmCommand();
@@ -256,11 +251,18 @@ async function executeGitHubCommand(command, args = [], options = {}) {
     if (!isValidGhCommand(command)) {
         return createErrorResult('Command not registered', new Error(`GitHub command '${command}' is not in the allowed list`));
     }
-    // Build command with validated prefix - no sanitization needed since we control the prefix
-    const fullCommand = `gh ${command} ${args.join(' ')}`;
-    const executeGhCommand = () => executeCommand(fullCommand, 'github', options);
+    // Get shell configuration
+    const shellConfig = getShellConfig(options.windowsShell);
+    // Build command with validated prefix and properly escaped arguments
+    const escapedArgs = args.map(arg => escapeShellArg(arg, shellConfig.type));
+    const fullCommand = `gh ${command} ${escapedArgs.join(' ')}`;
+    const executeGhCommand = () => executeCommand(fullCommand, 'github', options, shellConfig);
     if (options.cache) {
-        const cacheKey = generateCacheKey('gh-exec', { command, args });
+        const cacheKey = generateCacheKey('gh-exec', {
+            command,
+            args,
+            shell: shellConfig.type,
+        });
         return withCache(cacheKey, executeGhCommand);
     }
     return executeGhCommand();
@@ -269,21 +271,23 @@ async function executeGitHubCommand(command, args = [], options = {}) {
  * Execute shell commands with timeout and error handling
  * Security: Should only be called with pre-validated command prefixes
  */
-async function executeCommand(fullCommand, type, options = {}) {
+async function executeCommand(fullCommand, type, options = {}, shellConfig) {
     try {
         const defaultTimeout = type === 'npm' ? 30000 : 60000;
+        const config = shellConfig || getShellConfig(options.windowsShell);
         const execOptions = {
             timeout: options.timeout || defaultTimeout,
+            maxBuffer: 5 * 1024 * 1024, // 5MB buffer limit (increased from default 1MB)
             cwd: options.cwd,
             env: {
                 ...process.env,
                 ...options.env,
-                // Ensure clean shell environment
-                SHELL: '/bin/sh',
+                // Ensure clean shell environment - cross-platform compatible
+                SHELL: config.shellEnv,
                 PATH: process.env.PATH,
             },
             encoding: 'utf-8',
-            shell: '/bin/sh', // Use sh instead of default shell
+            shell: config.shell, // Use platform-appropriate shell
         };
         const { stdout, stderr } = await safeExecAsync(fullCommand, execOptions);
         // Handle different warning patterns for npm vs gh
@@ -303,6 +307,9 @@ async function executeCommand(fullCommand, type, options = {}) {
             result: stdout,
             timestamp: new Date().toISOString(),
             type,
+            platform: platform(),
+            shell: config.shell,
+            shellType: config.type,
             ...(stderr && { warning: stderr }), // Include warnings but don't treat as error
         });
     }
@@ -314,10 +321,13 @@ async function executeCommand(fullCommand, type, options = {}) {
     }
 }
 
+const TOOL_NAME$9 = 'api_status_check';
+const DESCRIPTION$9 = `Gets the list of user github  organizations (in case the tool needs to use them in "owner" fields in github search) and checks users gh cli and npm cli login status.
+Use when user asks on specific implementaon in his organization (e.g. - I work at Wix, or search Wix code about X) or when cli is failing.`;
 function registerApiStatusCheckTool(server) {
-    server.tool(TOOL_NAMES.API_STATUS_CHECK, TOOL_DESCRIPTIONS[TOOL_NAMES.API_STATUS_CHECK], {}, {
-        title: TOOL_NAMES.API_STATUS_CHECK,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.API_STATUS_CHECK],
+    server.tool(TOOL_NAME$9, DESCRIPTION$9, {}, {
+        title: 'Check API Connections and Github Organizations',
+        description: DESCRIPTION$9,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -433,64 +443,56 @@ function registerApiStatusCheckTool(server) {
             });
         }
         catch (error) {
-            return createResult(`API status check failed: ${error.message}`, true);
+            return createResult('API status check failed - verify GitHub CLI and NPM are installed and accessible', true);
         }
     });
 }
 
-/**
- * Registers the GitHub Code Search tool with the MCP server.
- *
- * This tool provides semantic code search across GitHub repositories using the GitHub CLI.
- * It supports advanced search features like boolean operators, qualifiers, and filters.
- *
- * Key features:
- * - Boolean operator support (AND, OR, NOT) in queries
- * - GitHub qualifier support (language:, path:, etc.)
- * - Repository, owner, and organization filtering
- * - File type, size, and visibility filtering
- * - Multiple match scopes and filtering options
- */
+const TOOL_NAME$8 = 'github_search_code';
+const DESCRIPTION$8 = `Search code across GitHub repositories using strategic boolean operators and filters with "gh code search" command.
+
+SEARCH PATTERNS:
+ OR (broad): "useState hook" → "useState OR hook" (auto-default for multi-word)
+ AND (precise): "react AND hooks" (both terms required)
+ NOT (filter): "auth NOT test" (exclude unwanted)
+ Exact phrases: "useState hook" (quoted for literal match)
+ Combine with filters: language, owner, path for laser focus
+
+RESTRICTIVENESS: OR (broadest) < AND < Exact Phrase (most precise)`;
 function registerGitHubSearchCodeTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_CODE], {
+    server.tool(TOOL_NAME$8, DESCRIPTION$8, {
         query: z
             .string()
             .min(1)
-            .describe('Search query with boolean operators (AND, OR, NOT) and qualifiers. ' +
-            'Examples: "react lifecycle", "error handling", "logger AND debug", "config OR settings", "main NOT test". ' +
-            'Use quotes for exact phrases. Supports GitHub search syntax.'),
+            .describe('Search query with strategic boolean operators. SEARCH PATTERNS: OR (auto-default): "useState hook" → "useState OR hook" for BROADEST discovery. AND (explicit): "react AND hooks" requires BOTH terms for RESTRICTIVE intersection. EXACT PHRASE (escaped quotes): "useState hook" finds literal sequence for MOST PRECISE targeting. NOT (filtering): "auth NOT test" excludes unwanted results. USAGE GUIDE: Use OR for exploration/alternatives, AND for specific combinations, exact phrases for documentation/APIs, NOT for removing noise. RESTRICTIVENESS: OR < AND < Exact Phrase. No parentheses - simple boolean logic only.'),
         owner: z
             .union([z.string(), z.array(z.string())])
             .optional()
-            .describe('Repository owner/organization(s). Single string or array for multiple owners. Leave empty for global search.'),
+            .describe('Repository owner/organization filter. Examples: "microsoft", "google". Combines with other filters for targeted search. get from user orgamizations in case of private repositories search (e.g. for employees of organizations)'),
         repo: z
             .union([z.string(), z.array(z.string())])
             .optional()
-            .describe('Specific repositories in "owner/repo" format. Can be a single repository string or array of repository strings. Requires owner parameter to be set.'),
+            .describe('Specific repositories in "owner/repo" format. Examples: "facebook/react", "microsoft/vscode". Requires owner parameter.'),
         language: z
             .string()
             .optional()
-            .describe('Programming language filter (e.g., "javascript", "python", "go").'),
+            .describe('Programming language filter. Examples: "javascript", "python", "typescript", "go". Highly effective for targeted searches.'),
         extension: z
             .string()
             .optional()
-            .describe('File extension filter without dot (e.g., "js", "py", "md").'),
+            .describe('File extension filter without dot. Examples: "js", "ts", "py", "md", "json". Precise file type targeting.'),
         filename: z
             .string()
             .optional()
-            .describe('Exact filename filter (e.g., "package.json", "Dockerfile", "README.md").'),
+            .describe('Exact filename filter. Examples: "package.json", "Dockerfile", "README.md", "index.js". Perfect for config files.'),
         path: z
             .string()
             .optional()
-            .describe('Directory path filter with wildcards (e.g., "src/", "*/tests/*", "docs/**").'),
+            .describe('Directory path filter. Examples: "src/", "test/", "docs/", "components/". Focus search on specific directories.'),
         size: z
             .string()
             .optional()
             .describe('File size filter in KB with operators (e.g., ">100", "<50", "10..100").'),
-        visibility: z
-            .enum(['public', 'private', 'internal'])
-            .optional()
-            .describe('Repository visibility filter. "public" for public repos, "private" for private repos you have access to.'),
         limit: z
             .number()
             .int()
@@ -502,18 +504,24 @@ function registerGitHubSearchCodeTool(server) {
         match: z
             .union([z.enum(['file', 'path']), z.array(z.enum(['file', 'path']))])
             .optional()
-            .describe('Search scope: "file" for content search, "path" for filename/path search. If array provided, only first value is used due to GitHub API limitations.'),
+            .describe('Search scope: "file" searches code content, "path" searches filenames/paths. Use "path" to find files by name.'),
+        visibility: z
+            .enum(['public', 'private', 'internal'])
+            .optional()
+            .describe('Repository visibility filter: "public", "private", or "internal". Defaults to accessible repositories.'),
     }, {
-        title: TOOL_NAMES.GITHUB_SEARCH_CODE,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_CODE],
+        title: TOOL_NAME$8,
+        description: DESCRIPTION$8,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: true,
     }, async (args) => {
         try {
-            if (args.repo && !args.owner) {
-                return createResult('Repository search requires owner parameter', true);
+            // Validate parameter combinations
+            const validationError = validateSearchParameters(args);
+            if (validationError) {
+                return createResult(validationError, true);
             }
             const result = await searchGitHubCode(args);
             if (result.isError) {
@@ -525,113 +533,268 @@ function registerGitHubSearchCodeTool(server) {
             const items = Array.isArray(codeResults) ? codeResults : [];
             return createSuccessResult$1({
                 query: args.query,
+                processed_query: parseSearchQuery(args.query, args),
                 total_count: items.length,
                 items: items,
+                cli_command: execResult.command,
+                debug_info: {
+                    has_complex_boolean_logic: hasComplexBooleanLogic(args.query),
+                    escaped_args: buildGitHubCliArgs(args),
+                    original_query: args.query,
+                },
             });
         }
         catch (error) {
-            return createErrorResult$1('Code search failed', error);
+            const errorMessage = error.message || '';
+            // Handle JSON parsing errors
+            if (errorMessage.includes('JSON')) {
+                return createErrorResult$1('GitHub CLI returned invalid response - check if GitHub CLI is up to date with "gh version" and try again', error);
+            }
+            return createErrorResult$1('GitHub code search failed - verify parameters and try with simpler query or specific filters (language, owner, path)', error);
         }
     });
 }
+/**
+ * Enhanced query parser that handles exact strings, boolean operators, and filters
+ */
+function parseSearchQuery(query, filters) {
+    // Step 1: Handle quoted strings more intelligently
+    // Convert escaped quotes to simple quotes to avoid shell escaping issues
+    let processedQuery = query.replace(/\\"/g, '"');
+    // Step 2: Preserve exact phrases (quoted strings)
+    const exactPhrases = [];
+    // Extract quoted strings and replace with placeholders
+    const quotedMatches = processedQuery.match(/"[^"]+"/g) || [];
+    quotedMatches.forEach((match, index) => {
+        const placeholder = `__EXACT_PHRASE_${index}__`;
+        exactPhrases.push(match);
+        processedQuery = processedQuery.replace(match, placeholder);
+    });
+    // Step 3: Check complexity BEFORE adding auto-OR logic
+    const originalHasComplexLogic = hasComplexBooleanLogic(processedQuery);
+    // Step 4: Smart boolean logic - default to OR between terms if no explicit operators
+    let searchQuery = processedQuery;
+    // Check if query already has explicit boolean operators
+    if (!originalHasComplexLogic) {
+        // Split by whitespace and join with OR for better search results
+        const terms = processedQuery
+            .trim()
+            .split(/\s+/)
+            .filter(term => term.length > 0);
+        if (terms.length > 1) {
+            searchQuery = terms.join(' OR ');
+        }
+    }
+    // Step 5: Handle filters differently based on ORIGINAL query complexity
+    const githubFilters = [];
+    // Always add path and visibility to query string (they don't have CLI equivalents)
+    if (filters.path) {
+        githubFilters.push(`path:${filters.path}`);
+    }
+    if (filters.visibility) {
+        githubFilters.push(`visibility:${filters.visibility}`);
+    }
+    // For complex boolean queries, add ALL filters to query string to avoid CLI conflicts
+    if (originalHasComplexLogic) {
+        if (filters.language) {
+            githubFilters.push(`language:${filters.language}`);
+        }
+        // For complex queries with both language and extension, prioritize language
+        if (filters.extension && !filters.language) {
+            githubFilters.push(`extension:${filters.extension}`);
+        }
+        if (filters.filename) {
+            githubFilters.push(`filename:${filters.filename}`);
+        }
+        if (filters.size) {
+            githubFilters.push(`size:${filters.size}`);
+        }
+    }
+    // Step 6: Combine query with GitHub filters using proper spacing
+    if (githubFilters.length > 0) {
+        searchQuery = `${searchQuery} ${githubFilters.join(' ')}`;
+    }
+    // Step 7: Restore exact phrases
+    exactPhrases.forEach((phrase, index) => {
+        const placeholder = `__EXACT_PHRASE_${index}__`;
+        searchQuery = searchQuery.replace(placeholder, phrase);
+    });
+    return searchQuery.trim();
+}
+/**
+ * Check if query contains complex boolean logic that might conflict with CLI flags
+ */
+function hasComplexBooleanLogic(query) {
+    const booleanOperators = /\b(AND|OR|NOT)\b/i;
+    return booleanOperators.test(query);
+}
+/**
+ * Build command line arguments for GitHub CLI with improved parameter handling
+ */
+function buildGitHubCliArgs(params) {
+    const args = ['code'];
+    // Parse and add the main search query
+    const searchQuery = parseSearchQuery(params.query, params);
+    args.push(searchQuery);
+    // Determine strategy based on ORIGINAL query complexity, not processed query
+    const hasComplexLogic = hasComplexBooleanLogic(params.query);
+    // For simple queries, use CLI flags for better performance and validation
+    if (!hasComplexLogic) {
+        if (params.language) {
+            args.push(`--language=${params.language}`);
+        }
+        if (params.extension) {
+            args.push(`--extension=${params.extension}`);
+        }
+        if (params.filename) {
+            args.push(`--filename=${params.filename}`);
+        }
+        if (params.size) {
+            args.push(`--size=${params.size}`);
+        }
+    }
+    // For complex queries, filters are already in the query string (handled by parseSearchQuery)
+    // Always add limit
+    if (params.limit) {
+        args.push(`--limit=${params.limit}`);
+    }
+    // Handle match parameter with conflict resolution
+    if (params.match) {
+        const matchValues = Array.isArray(params.match)
+            ? params.match
+            : [params.match];
+        // Use the first match type when multiple are provided
+        const matchValue = matchValues[0];
+        args.push(`--match=${matchValue}`);
+    }
+    // Handle owner parameter - can be string or array
+    if (params.owner && !params.repo) {
+        const ownerValues = Array.isArray(params.owner)
+            ? params.owner
+            : [params.owner];
+        ownerValues.forEach(owner => args.push(`--owner=${owner}`));
+    }
+    // Handle repository filters with improved validation
+    if (params.owner && params.repo) {
+        const owners = Array.isArray(params.owner) ? params.owner : [params.owner];
+        const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
+        // Create repo filters for each owner/repo combination
+        owners.forEach(owner => {
+            repos.forEach(repo => {
+                // Handle both "owner/repo" format and just "repo" format
+                if (repo.includes('/')) {
+                    args.push(`--repo=${repo}`);
+                }
+                else {
+                    args.push(`--repo=${owner}/${repo}`);
+                }
+            });
+        });
+    }
+    // JSON output with all available fields
+    args.push('--json=repository,path,textMatches,sha,url');
+    return args;
+}
 async function searchGitHubCode(params) {
     const cacheKey = generateCacheKey('gh-code', params);
     return withCache(cacheKey, async () => {
         try {
-            const args = ['code'];
-            // Build the main query - preserve boolean operators and GitHub syntax
-            let query = params.query;
-            // Add path filter to query if provided (GitHub search syntax)
-            if (params.path) {
-                query = `${query} path:${params.path}`;
-            }
-            // Add visibility filter to query if provided
-            if (params.visibility) {
-                query = `${query} visibility:${params.visibility}`;
-            }
-            args.push(query);
-            // Add command-line filters
-            if (params.language)
-                args.push(`--language=${params.language}`);
-            if (params.extension)
-                args.push(`--extension=${params.extension}`);
-            if (params.filename)
-                args.push(`--filename=${params.filename}`);
-            if (params.size)
-                args.push(`--size=${params.size}`);
-            if (params.limit)
-                args.push(`--limit=${params.limit}`);
-            // Handle match parameter - can be string or array
-            // Note: GitHub search API doesn't support multiple match types in a single query
-            if (params.match) {
-                const matchValues = Array.isArray(params.match)
-                    ? params.match
-                    : [params.match];
-                // GitHub API limitation: can't use both in:file and in:path in same query
-                // Use the first match type when multiple are provided
-                const matchValue = matchValues[0];
-                args.push(`--match=${matchValue}`);
-            }
-            // Handle owner parameter - can be string or array
-            if (params.owner && !params.repo) {
-                const ownerValues = Array.isArray(params.owner)
-                    ? params.owner
-                    : [params.owner];
-                ownerValues.forEach(owner => args.push(`--owner=${owner}`));
-            }
-            // Handle repository filters
-            if (params.owner && params.repo) {
-                const owners = Array.isArray(params.owner)
-                    ? params.owner
-                    : [params.owner];
-                const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
-                // Create repo filters for each owner/repo combination
-                owners.forEach(owner => {
-                    repos.forEach(repo => {
-                        // Handle both "owner/repo" format and just "repo" format
-                        if (repo.includes('/')) {
-                            args.push(`--repo=${repo}`);
-                        }
-                        else {
-                            args.push(`--repo=${owner}/${repo}`);
-                        }
-                    });
-                });
-            }
-            // JSON output with all available fields
-            args.push('--json=repository,path,textMatches,sha,url');
+            const args = buildGitHubCliArgs(params);
             const result = await executeGitHubCommand('search', args, {
                 cache: false,
             });
             return result;
         }
         catch (error) {
-            return createErrorResult$1('Failed to execute search command', error);
+            const errorMessage = error.message || '';
+            // Parse specific GitHub CLI error types
+            if (errorMessage.includes('authentication')) {
+                return createErrorResult$1('GitHub CLI authentication required - run the api_status_check tool to verify authentication and available organizations', error);
+            }
+            if (errorMessage.includes('rate limit')) {
+                return createErrorResult$1('GitHub API rate limit exceeded - wait a few minutes before searching again or use more specific filters to reduce results', error);
+            }
+            if (errorMessage.includes('validation failed') ||
+                errorMessage.includes('Invalid query')) {
+                return createErrorResult$1('Invalid search query syntax - check boolean operators (AND/OR/NOT), quotes for exact phrases, and filter formats. Try simplifying your query', error);
+            }
+            if (errorMessage.includes('repository not found') ||
+                errorMessage.includes('owner not found')) {
+                return createErrorResult$1('Repository or owner not found - run api_status_check tool to verify available organizations and access permissions', error);
+            }
+            if (errorMessage.includes('timeout')) {
+                return createErrorResult$1('Search timeout - query too broad or complex. Try adding filters like language, owner, or path to narrow results', error);
+            }
+            // Generic fallback with helpful guidance
+            return createErrorResult$1('GitHub code search failed - run api_status_check tool to verify authentication and permissions, or try simplifying your query', error);
         }
     });
 }
+/**
+ * Validate parameter combinations to prevent conflicts
+ */
+function validateSearchParameters(params) {
+    // Query validation
+    if (!params.query.trim()) {
+        return 'Empty search query - provide a search term like "useState", "function init", or "api AND endpoint"';
+    }
+    if (params.query.length > 1000) {
+        return 'Search query too long - limit to 1000 characters. Try breaking into smaller, focused searches';
+    }
+    // Repository validation
+    if (params.repo && !params.owner) {
+        return 'Missing owner parameter - when searching specific repositories, format as owner/repo (e.g., "microsoft/vscode") or provide both owner and repo parameters';
+    }
+    // Invalid characters in query
+    if (params.query.includes('\\') && !params.query.includes('\\"')) {
+        return 'Invalid escape characters in query - use quotes for exact phrases: "exact phrase" instead of escaping';
+    }
+    // Boolean operator validation
+    const invalidBooleans = params.query.match(/\b(and|or|not)\b/g);
+    if (invalidBooleans) {
+        return `Boolean operators must be uppercase - use ${invalidBooleans.map(op => op.toUpperCase()).join(', ')} instead of ${invalidBooleans.join(', ')}`;
+    }
+    // Unmatched quotes
+    const quoteCount = (params.query.match(/"/g) || []).length;
+    if (quoteCount % 2 !== 0) {
+        return 'Unmatched quotes in query - ensure all quotes are properly paired for exact phrase matching';
+    }
+    // Size parameter validation
+    if (params.size && !/^[<>]=?\d+$|^\d+\.\.\d+$|^\d+$/.test(params.size)) {
+        return 'Invalid size format - use ">100", "<50", "10..100", or "100" for file size filtering';
+    }
+    return null; // No validation errors
+}
 
+const TOOL_NAME$7 = 'github_get_file_content';
+const DESCRIPTION$7 = `Read file content. This tool REQUIRES exact path verification from github_get_contents or package view exports. If fetching fails, re-check file existence with github_get_contents or branch name.`;
 function registerFetchGitHubFileContentTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_GET_FILE_CONTENT, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_FILE_CONTENT], {
+    server.tool(TOOL_NAME$7, DESCRIPTION$7, {
         owner: z
             .string()
             .min(1)
+            .max(100)
+            .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/)
             .describe(`Repository owner/organization (e.g., 'microsoft', 'facebook')`),
         repo: z
             .string()
             .min(1)
+            .max(100)
+            .regex(/^[a-zA-Z0-9._-]+$/)
             .describe(`Repository name (e.g., 'vscode', 'react'). Case-sensitive.`),
         branch: z
             .string()
             .min(1)
+            .max(255)
+            .regex(/^[^\s]+$/)
             .describe(`Branch name (e.g., 'main', 'master'). Auto-fallback to common branches if not found.`),
         filePath: z
             .string()
             .min(1)
             .describe(`File path from repository root (e.g., 'README.md', 'src/index.js'). Use github_get_contents to explore structure.`),
     }, {
-        title: TOOL_NAMES.GITHUB_GET_FILE_CONTENT,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_FILE_CONTENT],
+        title: TOOL_NAME$7,
+        description: DESCRIPTION$7,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -666,26 +829,7 @@ function registerFetchGitHubFileContentTool(server) {
             return result;
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            let suggestions = [];
-            if (errorMessage.includes('404') ||
-                errorMessage.includes('Not Found')) {
-                suggestions = [
-                    TOOL_NAMES.GITHUB_GET_CONTENTS,
-                    TOOL_NAMES.GITHUB_SEARCH_CODE,
-                ];
-            }
-            else if (errorMessage.includes('403') ||
-                errorMessage.includes('Forbidden')) {
-                suggestions = [TOOL_NAMES.API_STATUS_CHECK];
-            }
-            else if (errorMessage.includes('branch')) {
-                suggestions = [TOOL_NAMES.GITHUB_GET_CONTENTS];
-            }
-            else {
-                suggestions = getErrorSuggestions(TOOL_NAMES.GITHUB_GET_FILE_CONTENT);
-            }
-            return createResult(`Failed to fetch file content: ${errorMessage}. Context: ${args.owner}/${args.repo}/${args.filePath} on ${args.branch}`, true, suggestions);
+            return createResult('File fetch failed - verify file path exists or try github_get_contents first', true);
         }
     });
 }
@@ -718,19 +862,35 @@ async function fetchGitHubFileContent(params) {
                 }
                 // Handle common errors
                 if (errorMsg.includes('404')) {
-                    return createErrorResult$1(`File not found: ${filePath}`, new Error(`File does not exist in ${owner}/${repo} on branch ${branch}`));
+                    return createErrorResult$1('File not found - verify path with github_get_contents first', new Error(filePath));
                 }
                 else if (errorMsg.includes('403')) {
-                    return createErrorResult$1(`Access denied: ${filePath}`, new Error(`Permission denied for ${owner}/${repo}`));
+                    return createErrorResult$1('Access denied - repository may be private or require authentication', new Error(`${owner}/${repo}`));
+                }
+                else if (errorMsg.includes('maxBuffer') ||
+                    errorMsg.includes('stdout maxBuffer length exceeded')) {
+                    return createErrorResult$1(` File too large to fetch (buffer limit exceeded)\n\n` +
+                        `This usually happens with files >300KB. Consider:\n` +
+                        `    Use github_search_code to find specific patterns\n` +
+                        `    Browse directory structure with github_get_contents`, new Error(`Buffer overflow: ${filePath}`));
                 }
                 else {
-                    return createErrorResult$1(`Failed to fetch file: ${filePath}`, new Error(errorMsg));
+                    return createErrorResult$1('Fetch failed - check repository and file path', new Error(errorMsg));
                 }
             }
             return await processFileContent(result, owner, repo, branch, filePath);
         }
         catch (error) {
-            return createErrorResult$1(`Unexpected error fetching file: ${filePath}`, error);
+            const errorMessage = error.message;
+            // Handle maxBuffer errors that escape the main try-catch
+            if (errorMessage.includes('maxBuffer') ||
+                errorMessage.includes('stdout maxBuffer length exceeded')) {
+                return createErrorResult$1(` File too large to fetch (buffer limit exceeded)\n\n` +
+                    `This usually happens with files >300KB. Consider:\n` +
+                    `    Use github_search_code to find specific patterns instead of fetching the whole file\n` +
+                    `    Browse directory structure with github_get_contents`, error);
+            }
+            return createErrorResult$1('Unexpected error during file fetch - check connection and permissions', error);
         }
     });
 }
@@ -740,30 +900,35 @@ async function processFileContent(result, owner, repo, branch, filePath) {
     const fileData = JSON.parse(execResult.result);
     // Check if it's a directory
     if (Array.isArray(fileData)) {
-        return createErrorResult$1(`Path is a directory: ${filePath}`, new Error(`"${filePath}" is a directory, not a file`));
+        return createErrorResult$1('Path is directory - use github_get_contents to browse directory structure', new Error(filePath));
     }
     const fileSize = fileData.size || 0;
-    const MAX_FILE_SIZE = 500 * 1024; // 500KB limit for simplicity
-    // Check file size
+    const MAX_FILE_SIZE = 300 * 1024; // 300KB limit for better performance and reliability
+    // Check file size with helpful message
     if (fileSize > MAX_FILE_SIZE) {
-        return createErrorResult$1(`File too large: ${filePath}`, new Error(`File size (${Math.round(fileSize / 1024)}KB) exceeds limit (500KB)`));
+        const fileSizeKB = Math.round(fileSize / 1024);
+        const maxSizeKB = Math.round(MAX_FILE_SIZE / 1024);
+        return createErrorResult$1(` File too large to display (${fileSizeKB}KB > ${maxSizeKB}KB limit)\n\n` +
+            `For large files like this, consider:\n` +
+            `    Use github_get_contents to browse directory structure\n` +
+            `    Search specific code patterns with github_search_code`, new Error(`File: ${filePath} (${fileSizeKB}KB)`));
     }
     // Get and decode content
     const base64Content = fileData.content?.replace(/\s/g, ''); // Remove all whitespace
     if (!base64Content) {
-        return createErrorResult$1(`Empty file: ${filePath}`, new Error(`File appears to be empty`));
+        return createErrorResult$1('Empty file - file has no content to display', new Error(filePath));
     }
     let decodedContent;
     try {
         const buffer = Buffer.from(base64Content, 'base64');
         // Simple binary check - look for null bytes
         if (buffer.indexOf(0) !== -1) {
-            return createErrorResult$1(`Binary file detected: ${filePath}`, new Error(`Binary files cannot be displayed as text`));
+            return createErrorResult$1('Binary file detected - cannot display binary content as text', new Error(filePath));
         }
         decodedContent = buffer.toString('utf-8');
     }
     catch (decodeError) {
-        return createErrorResult$1(`Failed to decode file: ${filePath}`, new Error(`Unable to decode file as UTF-8`));
+        return createErrorResult$1('Decode failed - file encoding not supported or corrupted', new Error(filePath));
     }
     // Return simplified response
     const response = {
@@ -781,8 +946,17 @@ async function processFileContent(result, owner, repo, branch, filePath) {
     return createSuccessResult$1(response);
 }
 
+const TOOL_NAME$6 = 'github_search_repositories';
+const DESCRIPTION$6 = `Search repositories by name/description. Start shallow and go broad: use topics for exploratory discovery (e.g., topic:["cli","typescript","api"]) to find ecosystem patterns.
+  PRIMARY FILTERS work alone: owner, language, stars, topic, forks. SECONDARY FILTERS require a query or primary filter: license, created, archived, includeForks, updated, visibility, match.
+  SMART REPOS SEARCH PATTERNS: Use topic:["cli","typescript"] for semantic discovery; stars:">100" for quality; owner:"microsoft" for organization repos. Query supports GitHub syntax: "language:Go OR language:Rust".
+  
+  EFFICIENCY NOTE: If you have a package name, use npm_view_package FIRST to get repositoryGitUrl - this tool becomes UNNECESSARY
+  
+  SMART INTEGRATION: When finding packages → npm_view_package + npm_package_search provide direct repo access
+  AVOID: Searching for "react" repos when npm_view_package("react") gives you the exact repository instantly`;
 function registerSearchGitHubReposTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_REPOS, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_REPOS], {
+    server.tool(TOOL_NAME$6, DESCRIPTION$6, {
         query: z
             .string()
             .optional()
@@ -791,52 +965,66 @@ function registerSearchGitHubReposTool(server) {
         owner: z
             .string()
             .optional()
-            .describe('Repository owner/organization. PRIMARY FILTER - works alone.'),
+            .describe('Repository owner/organization (e.g., "microsoft", "facebook").'),
         language: z
             .string()
             .optional()
-            .describe('Programming language. PRIMARY FILTER - works alone.'),
+            .describe('Programming language (e.g., "javascript", "python", "go").'),
         stars: z
             .string()
             .optional()
-            .describe('Stars count with ranges: "100", ">500", "<50", "10..100", ">=1000". PRIMARY FILTER - works alone. Use >100 for quality projects.'),
+            .describe('Stars count with ranges: "100", ">500", "<50", "10..100", ">=1000". Use >100 for quality projects.'),
         topic: z
             .array(z.string())
             .optional()
-            .describe('Filter by topics. PRIMARY FILTER - works alone.'),
-        forks: z
+            .describe('Filter by topics (e.g., ["cli", "typescript", "api"]).'),
+        forks: z.number().optional().describe('Exact forks count.'),
+        numberOfTopics: z
             .number()
             .optional()
-            .describe('Exact forks count. PRIMARY FILTER - works alone.'),
+            .describe('Filter on number of topics.'),
         // SECONDARY FILTERS (require query or primary filter)
         license: z
             .array(z.string())
             .optional()
-            .describe('License types. REQUIRES query or primary filter.'),
+            .describe('License types (e.g., ["mit", "apache-2.0"]).'),
         match: z
             .enum(['name', 'description', 'readme'])
             .optional()
-            .describe('Search scope. REQUIRES query.'),
+            .describe('Search scope: "name", "description", or "readme".'),
         visibility: z
             .enum(['public', 'private', 'internal'])
             .optional()
-            .describe('Repository visibility. REQUIRES query or primary filter.'),
+            .describe('Repository visibility filter.'),
         created: z
             .string()
             .optional()
-            .describe('Created date filter: ">2020-01-01", "<2023-12-31". REQUIRES query or primary filter.'),
+            .describe('Created date filter: ">2020-01-01", "<2023-12-31", "2022-01-01..2023-12-31".'),
         updated: z
             .string()
             .optional()
-            .describe('Updated date filter. REQUIRES query or primary filter.'),
-        archived: z
-            .boolean()
-            .optional()
-            .describe('Archived state. REQUIRES query or primary filter.'),
+            .describe('Updated date filter (same format as created).'),
+        archived: z.boolean().optional().describe('Filter by archived state.'),
         includeForks: z
             .enum(['false', 'true', 'only'])
             .optional()
-            .describe('Include forks. REQUIRES query or primary filter.'),
+            .describe('Include forks: "false" (default), "true", or "only".'),
+        goodFirstIssues: z
+            .string()
+            .optional()
+            .describe('Filter by good first issues count (e.g., ">=10", ">5").'),
+        helpWantedIssues: z
+            .string()
+            .optional()
+            .describe('Filter by help wanted issues count (e.g., ">=5", ">10").'),
+        followers: z
+            .number()
+            .optional()
+            .describe('Filter by number of followers.'),
+        size: z
+            .string()
+            .optional()
+            .describe('Repository size filter in KB (e.g., ">100", "<50", "10..100").'),
         // Sorting and limits
         sort: z
             .enum(['forks', 'help-wanted-issues', 'stars', 'updated', 'best-match'])
@@ -857,8 +1045,8 @@ function registerSearchGitHubReposTool(server) {
             .default(25)
             .describe('Maximum results (default: 25, max: 50)'),
     }, {
-        title: TOOL_NAMES.GITHUB_SEARCH_REPOS,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_REPOS],
+        title: TOOL_NAME$6,
+        description: DESCRIPTION$6,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -880,7 +1068,7 @@ function registerSearchGitHubReposTool(server) {
             return result;
         }
         catch (error) {
-            return createResult(`Search failed: ${error.message}`, true, getErrorSuggestions(TOOL_NAMES.GITHUB_SEARCH_REPOS));
+            return createResult('Repository search failed - check query syntax, filters, or try broader terms', true);
         }
     });
 }
@@ -947,7 +1135,7 @@ async function searchGitHubRepos(params) {
                     isPrivate: repo.isPrivate || false,
                     isArchived: repo.isArchived || false,
                     isFork: repo.isFork || false,
-                    topics: [], // Topics not available via CLI JSON output
+                    topics: [], // GitHub CLI search repos doesn't provide topics in JSON output
                     license: repo.license?.name || null,
                     hasIssues: repo.hasIssues || false,
                     openIssuesCount: repo.openIssuesCount || 0,
@@ -971,55 +1159,31 @@ async function searchGitHubRepos(params) {
                     }
                     : {
                         repositories: [],
-                        suggestions: [
-                            `${TOOL_NAMES.NPM_PACKAGE_SEARCH} "${params.query || 'package'}"`,
-                            `${TOOL_NAMES.GITHUB_SEARCH_CODE} "${params.query || 'code'}"`,
-                            'Try broader search terms',
-                            'Check spelling and try synonyms',
-                        ],
                     }),
             });
         }
         catch (error) {
-            return createErrorResult$1('Failed to search GitHub repositories', error);
+            return createErrorResult$1('GitHub repository search failed - verify connection or try simpler query', error);
         }
     });
 }
 function buildGitHubReposSearchCommand(params) {
     // Build query following GitHub CLI patterns
     const query = params.query?.trim() || '';
-    // Handle complex queries (with qualifiers, operators, or --) differently
-    const hasComplexSyntax = query.includes('--') ||
-        query.includes(':') ||
-        query.includes('OR') ||
-        query.includes('AND') ||
-        query.includes('(') ||
-        query.includes(')') ||
-        query.startsWith('-');
     const args = ['repos'];
-    // Only add query if it exists
+    // Only add query if it exists and handle it properly
     if (query) {
-        if (hasComplexSyntax) {
-            // For complex queries with special syntax, we need to be more careful
-            // Split by spaces but preserve quoted strings and handle special characters
-            const queryParts = query.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
-            queryParts.forEach(part => {
-                // If part contains shell special characters, quote it
-                if (/[><=&|$`(){}[\];\\]/.test(part) && !part.includes('"')) {
-                    args.push(`"${part}"`);
-                }
-                else {
-                    args.push(part);
-                }
-            });
+        // For repository search, treat multi-word queries as a single quoted string
+        // This matches GitHub CLI expected behavior for repo searches
+        if (query.includes(' ')) {
+            args.push(query); // Let GitHub CLI handle the quoting
         }
         else {
-            // For simple queries, use quoting logic
-            const queryString = needsQuoting(query) ? `"${query}"` : query;
-            args.push(queryString);
+            args.push(query);
         }
     }
     // Add JSON output with specific fields for structured data parsing
+    // Note: 'topics' field is not available in GitHub CLI search repos JSON output
     args.push('--json', 'name,fullName,description,language,stargazersCount,forksCount,updatedAt,createdAt,url,owner,isPrivate,license,hasIssues,openIssuesCount,isArchived,isFork,visibility');
     // PRIMARY FILTERS - Handle owner as single string (BaseSearchParams) or array
     if (params.owner) {
@@ -1034,6 +1198,8 @@ function buildGitHubReposSearchCommand(params) {
         args.push(`--forks=${params.forks}`);
     if (params.topic && params.topic.length > 0)
         args.push(`--topic=${params.topic.join(',')}`);
+    if (params.numberOfTopics !== undefined)
+        args.push(`--number-topics=${params.numberOfTopics}`);
     // Only add stars filter if it's a valid numeric value or range
     if (params.stars !== undefined &&
         params.stars !== '*' &&
@@ -1042,14 +1208,15 @@ function buildGitHubReposSearchCommand(params) {
         const starsValue = params.stars.trim();
         const isValidStars = /^(\d+|>\d+|<\d+|\d+\.\.\d+|>=\d+|<=\d+)$/.test(starsValue);
         if (isValidStars) {
-            args.push(`--stars="${params.stars}"`);
+            // Don't add quotes around the stars value - GitHub CLI handles this internally
+            args.push(`--stars=${starsValue}`);
         }
     }
     // SECONDARY FILTERS - only add if we have primary filters
     if (params.archived !== undefined)
         args.push(`--archived=${params.archived}`);
     if (params.created)
-        args.push(`--created="${params.created}"`);
+        args.push(`--created=${params.created}`);
     if (params.includeForks)
         args.push(`--include-forks=${params.includeForks}`);
     if (params.license && params.license.length > 0)
@@ -1057,9 +1224,17 @@ function buildGitHubReposSearchCommand(params) {
     if (params.match)
         args.push(`--match=${params.match}`);
     if (params.updated)
-        args.push(`--updated="${params.updated}"`);
+        args.push(`--updated=${params.updated}`);
     if (params.visibility)
         args.push(`--visibility=${params.visibility}`);
+    if (params.goodFirstIssues)
+        args.push(`--good-first-issues=${params.goodFirstIssues}`);
+    if (params.helpWantedIssues)
+        args.push(`--help-wanted-issues=${params.helpWantedIssues}`);
+    if (params.followers !== undefined)
+        args.push(`--followers=${params.followers}`);
+    if (params.size)
+        args.push(`--size=${params.size}`);
     // SORTING AND LIMITS
     if (params.limit)
         args.push(`--limit=${params.limit}`);
@@ -1073,12 +1248,14 @@ function buildGitHubReposSearchCommand(params) {
     return { command: 'search', args };
 }
 
+const TOOL_NAME$5 = 'github_search_commits';
+const DESCRIPTION$5 = `Search commit history with powerful boolean logic and exact phrase matching. Use advanced GitHub search syntax including AND/OR operators for precise commit discovery. Understand code evolution patterns, track bug fixes, and analyze development workflows over time. Filter by author, date ranges, commit content, and repository metadata with surgical precision.`;
 function registerSearchGitHubCommitsTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_COMMITS, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_COMMITS], {
+    server.tool(TOOL_NAME$5, DESCRIPTION$5, {
         query: z
             .string()
             .optional()
-            .describe('Search query with full GitHub syntax support: "readme typo" (AND), "bug fix" (phrase), "author:john OR committer:jane" (OR), "-- -author:botuser" (exclude). Optional - can search with just filters.'),
+            .describe('Search query with POWERFUL boolean logic and exact phrase matching. BOOLEAN OPERATORS: "fix AND bug" (both required), "fix OR update" (either term), "readme typo" (implicit AND). EXACT PHRASES: "initial commit" (precise phrase matching). ADVANCED SYNTAX: "author:john OR committer:jane" (user qualifiers), "-- -author:botuser" (exclusions). STRENGTH: Surgical precision for commit discovery across millions of repositories. Optional - can search with just filters.'),
         // Basic filters
         owner: z
             .string()
@@ -1135,10 +1312,10 @@ function registerSearchGitHubCommitsTool(server) {
             .max(50)
             .optional()
             .default(25)
-            .describe('Maximum results (default: 25)'),
+            .describe('Maximum results (default: 25, max: 50)'),
     }, {
-        title: TOOL_NAMES.GITHUB_SEARCH_COMMITS,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_COMMITS],
+        title: TOOL_NAME$5,
+        description: DESCRIPTION$5,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -1157,7 +1334,7 @@ function registerSearchGitHubCommitsTool(server) {
             return result;
         }
         catch (error) {
-            return createResult(`Search failed: ${error.message}`, true, getErrorSuggestions(TOOL_NAMES.GITHUB_SEARCH_COMMITS));
+            return createResult('Commit search failed - check query syntax, filters, or repository access', true);
         }
     });
 }
@@ -1252,17 +1429,10 @@ async function searchGitHubCommits(params) {
                 query: params.query,
                 total: 0,
                 commits: [],
-                suggestions: [
-                    `${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} "${params.query || 'pr'}"`,
-                    `${TOOL_NAMES.GITHUB_SEARCH_ISSUES} "${params.query || 'issue'}"`,
-                    `${TOOL_NAMES.GITHUB_SEARCH_CODE} "${params.query || 'code'}"`,
-                    'Try broader search terms',
-                    'Check spelling and try synonyms',
-                ],
             });
         }
         catch (error) {
-            return createErrorResult$1('Failed to search GitHub commits', error);
+            return createErrorResult$1('GitHub commit search failed - verify repository exists or try different filters', error);
         }
     });
 }
@@ -1352,12 +1522,20 @@ function buildGitHubCommitsSearchCommand(params) {
 }
 
 // TODO: add PR commeents. e.g, gh pr view <PR_NUMBER_OR_URL_OR_BRANCH> --comments
+const TOOL_NAME$4 = 'github_search_pull_requests';
+const DESCRIPTION$4 = `Find pull requests and implementations with detailed metadata. Discover feature implementations, code review patterns, and development workflows.
+
+SEARCH PATTERNS:
+ Boolean: "fix AND bug", "refactor OR cleanup", "feature NOT draft"
+ Exact phrases: "initial commit" (quoted)
+ GitHub qualifiers: "is:merged review:approved base:main"
+ Combine with filters for targeted PR discovery`;
 function registerSearchGitHubPullRequestsTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS], {
+    server.tool(TOOL_NAME$4, DESCRIPTION$4, {
         query: z
             .string()
             .min(1, 'Search query is required and cannot be empty')
-            .describe('Search query to find pull requests'),
+            .describe('Search query with GITHUB SEARCH SYNTAX support. BOOLEAN OPERATORS: "fix AND bug" (both required), "refactor OR cleanup" (either term), "feature NOT draft" (excludes). EXACT PHRASES: "initial commit" (precise matching). GITHUB QUALIFIERS: "is:merged review:approved base:main" (native GitHub syntax). COMBINED: Mix boolean logic with qualifiers for precise PR discovery.'),
         owner: z.string().optional().describe('Repository owner/organization'),
         repo: z.string().optional().describe('Repository name'),
         author: z.string().optional().describe('Filter by pull request author'),
@@ -1382,6 +1560,15 @@ function registerSearchGitHubPullRequestsTool(server) {
         mergedAt: z.string().optional().describe('Filter by merged date'),
         closed: z.string().optional().describe('Filter by closed date'),
         draft: z.boolean().optional().describe('Filter by draft state'),
+        checks: z
+            .enum(['pending', 'success', 'failure'])
+            .optional()
+            .describe('Filter based on status of the checks'),
+        merged: z.boolean().optional().describe('Filter based on merged state'),
+        review: z
+            .enum(['none', 'required', 'approved', 'changes_requested'])
+            .optional()
+            .describe('Filter based on review status'),
         limit: z
             .number()
             .int()
@@ -1389,7 +1576,7 @@ function registerSearchGitHubPullRequestsTool(server) {
             .max(50)
             .optional()
             .default(25)
-            .describe('Maximum results (default: 25)'),
+            .describe('Maximum results (default: 25, max: 50)'),
         sort: z
             .enum([
             'comments',
@@ -1412,24 +1599,24 @@ function registerSearchGitHubPullRequestsTool(server) {
             .default('desc')
             .describe('Order (default: desc)'),
     }, {
-        title: TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS],
+        title: TOOL_NAME$4,
+        description: DESCRIPTION$4,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: true,
     }, async (args) => {
         if (!args.query?.trim()) {
-            return createErrorResult$1('Search query is required and cannot be empty', new Error('Invalid query'));
+            return createErrorResult$1('Search query is required and cannot be empty - provide keywords to search for pull requests', new Error('Invalid query'));
         }
         if (args.query.length > 256) {
-            return createErrorResult$1('Search query is too long. Please limit to 256 characters or less.', new Error('Query too long'));
+            return createErrorResult$1('Search query is too long. Please limit to 256 characters or less - simplify your search terms', new Error('Query too long'));
         }
         try {
             return await searchGitHubPullRequests(args);
         }
         catch (error) {
-            return createErrorResult$1('Failed to search GitHub pull requests', error);
+            return createErrorResult$1('GitHub pull requests search failed - verify repository access and query syntax', error);
         }
     });
 }
@@ -1521,6 +1708,12 @@ function buildGitHubPullRequestsAPICommand(params) {
         queryParts.push(`merged:${params.mergedAt}`);
     if (params.draft !== undefined)
         queryParts.push(`draft:${params.draft}`);
+    if (params.checks)
+        queryParts.push(`status:${params.checks}`);
+    if (params.merged !== undefined)
+        queryParts.push(`is:${params.merged ? 'merged' : 'unmerged'}`);
+    if (params.review)
+        queryParts.push(`review:${params.review}`);
     // Add type qualifier to search only pull requests
     queryParts.push('type:pr');
     const query = queryParts.filter(Boolean).join(' ');
@@ -1533,13 +1726,22 @@ function buildGitHubPullRequestsAPICommand(params) {
     return { command: 'api', args: [apiPath] };
 }
 
+const TOOL_NAME$3 = 'npm_package_search';
+const DESCRIPTION$3 = `Search npm packages by keywords using fuzzy matching. 
+
+IMPORTANT LIMITATIONS:
+ NO BOOLEAN OPERATORS: NPM search does NOT support AND/OR/NOT - use space-separated keywords for broader search
+ FUZZY MATCHING ONLY: No exact phrase matching - searches are approximate keyword matching
+ KEYWORD-BASED: Best results with simple, space-separated terms like "react hooks" or "cli typescript"
+
+Required when package name is unknown. If you have the exact package name, use npm_view_package directly. This reduces the need to use GitHub search when packages are found.`;
 const MAX_DESCRIPTION_LENGTH = 100;
 const MAX_KEYWORDS = 10;
 function registerNpmSearchTool(server) {
-    server.tool(TOOL_NAMES.NPM_PACKAGE_SEARCH, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_PACKAGE_SEARCH], {
+    server.tool(TOOL_NAME$3, DESCRIPTION$3, {
         queries: z
             .union([z.string(), z.array(z.string())])
-            .describe('Package names or keywords to search for'),
+            .describe('Package names or keywords to search for. NOTE: No boolean operators (AND/OR/NOT) supported - use simple space-separated keywords like "react hooks" or "typescript cli" for fuzzy matching.'),
         searchlimit: z
             .number()
             .int()
@@ -1547,10 +1749,10 @@ function registerNpmSearchTool(server) {
             .max(50)
             .optional()
             .default(20)
-            .describe('Max results per query (default: 20)'),
+            .describe('Max results per query (default: 20, max: 50)'),
     }, {
-        title: TOOL_NAMES.NPM_PACKAGE_SEARCH,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_PACKAGE_SEARCH],
+        title: TOOL_NAME$3,
+        description: DESCRIPTION$3,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -1580,12 +1782,10 @@ function registerNpmSearchTool(server) {
                     results: deduplicatedPackages,
                 });
             }
-            const suggestions = getNoResultsSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH);
-            return createResult('No packages found', true, suggestions);
+            return createResult('No packages found', true);
         }
         catch (error) {
-            const suggestions = getErrorSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH);
-            return createResult(`Search failed: ${error.message}`, true, suggestions);
+            return createResult('NPM package search failed - check search terms or try different keywords', true);
         }
     });
 }
@@ -1637,8 +1837,10 @@ function parseNpmSearchOutput(output) {
     }
 }
 
+const TOOL_NAME$2 = 'github_get_contents';
+const DESCRIPTION$2 = `Browse repository structure and verify file existence. Use before github_get_file_content to confirm files exist and understand organization, especially when the path is uncertain.`;
 function registerViewRepositoryStructureTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_GET_CONTENTS, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_CONTENTS], {
+    server.tool(TOOL_NAME$2, DESCRIPTION$2, {
         owner: z
             .string()
             .min(1)
@@ -1668,8 +1870,8 @@ function registerViewRepositoryStructureTool(server) {
             .describe('Directory path within repository (e.g., "src/components", "packages/core"). ' +
             'Leave empty for root. Use previous results to navigate deeper.'),
     }, {
-        title: TOOL_NAMES.GITHUB_GET_CONTENTS,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_CONTENTS],
+        title: TOOL_NAME$2,
+        description: DESCRIPTION$2,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -1699,48 +1901,7 @@ function registerViewRepositoryStructureTool(server) {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            // Enhanced context-aware error suggestions
-            let suggestions = [];
-            const context = `${args.owner}/${args.repo}`;
-            if (errorMessage.includes('404') ||
-                errorMessage.includes('Not Found')) {
-                if (args.path) {
-                    suggestions = [
-                        `Try exploring root first: github_get_contents(owner: "${args.owner}", repo: "${args.repo}", branch: "${args.branch}", path: "")`,
-                        `Search for similar paths: github_search_code with path filters`,
-                    ];
-                }
-                else {
-                    suggestions = [
-                        `Search for repository: github_search_repositories(query: "${args.repo}")`,
-                        `Verify owner exists: github_search_repositories(owner: "${args.owner}")`,
-                    ];
-                }
-            }
-            else if (errorMessage.includes('403') ||
-                errorMessage.includes('Forbidden')) {
-                suggestions = [
-                    `Check authentication status: api_status_check`,
-                    `Try public repositories first to verify access`,
-                ];
-            }
-            else if (errorMessage.includes('rate limit')) {
-                suggestions = [
-                    `Check rate limit status: api_status_check`,
-                    `Wait before retrying or use authenticated requests`,
-                ];
-            }
-            else if (errorMessage.includes('invalid') ||
-                errorMessage.includes('branch')) {
-                suggestions = [
-                    `Find valid branches: github_search_repositories(query: "${context}")`,
-                    `Try common branches: main, master, develop`,
-                ];
-            }
-            else {
-                suggestions = getErrorSuggestions(TOOL_NAMES.GITHUB_GET_CONTENTS);
-            }
-            return createResult(`Repository exploration failed: ${errorMessage}. Context: ${context} on ${args.branch}${args.path ? ` at ${args.path}` : ''}`, true, suggestions);
+            return createResult(`Repository exploration failed: ${errorMessage} - verify repository exists and is accessible`, true);
         }
     });
 }
@@ -1751,7 +1912,7 @@ function registerViewRepositoryStructureTool(server) {
  * - Smart branch detection: fetches repository default branch automatically
  * - Intelligent fallback: tries requested -> default -> common branches
  * - Input validation: prevents path traversal and validates GitHub naming
- * - Enhanced error context: provides actionable suggestions for recovery
+ * - Clear error context: provides descriptive error messages
  * - Efficient caching: avoids redundant API calls
  */
 async function viewRepositoryStructure(params) {
@@ -1794,19 +1955,17 @@ async function viewRepositoryStructure(params) {
                 const errorMsg = lastError?.message || 'Unknown error';
                 if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
                     if (path) {
-                        throw new Error(`Path "${path}" not found in repository ${owner}/${repo}. ` +
-                            `Use github_get_contents with empty path first to discover the repository structure.`);
+                        throw new Error(`Path "${path}" not found - verify path exists or use github_search_code to find files`);
                     }
                     else {
-                        throw new Error(`Repository ${owner}/${repo} not found or no accessible branches. ` +
-                            `Tried branches: ${branchesToTry.join(', ')}`);
+                        throw new Error(`Repository not found: ${owner}/${repo} - verify owner/repo names or use github_search_repositories`);
                     }
                 }
                 else if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
-                    throw new Error(`Access denied to repository ${owner}/${repo}`);
+                    throw new Error(`Access denied to repository ${owner}/${repo} - repository may be private or require authentication`);
                 }
                 else {
-                    throw new Error(`Repository ${owner}/${repo} not found or path "${path}" doesn't exist`);
+                    throw new Error(`Access failed: ${owner}/${repo} - check connection or repository permissions`);
                 }
             }
             // Limit total items to 100 for efficiency
@@ -1864,7 +2023,7 @@ async function viewRepositoryStructure(params) {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            return createErrorResult$1(`Repository access failed: ${owner}/${repo}${path ? ` at ${path}` : ''}`, new Error(errorMessage));
+            return createErrorResult$1('Repository access failed - verify repository exists and check authentication', new Error(errorMessage));
         }
     });
 }
@@ -1900,12 +2059,20 @@ async function getSmartBranchFallback(owner, repo, requestedBranch) {
     return branches;
 }
 
+const TOOL_NAME$1 = 'github_search_issues';
+const DESCRIPTION$1 = `Find GitHub issues with rich metadata (labels, reactions, comments, state). Discover pain points, feature requests, and bug patterns with boolean logic and GitHub qualifiers.
+
+SEARCH PATTERNS:
+ Boolean: "bug AND crash", "feature OR enhancement", "error NOT test"
+ Exact phrases: "memory leak" (quoted)
+ GitHub qualifiers: "is:open label:bug author:username"
+ Combine with filters for precision`;
 function registerSearchGitHubIssuesTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_ISSUES, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_ISSUES], {
+    server.tool(TOOL_NAME$1, DESCRIPTION$1, {
         query: z
             .string()
             .min(1, 'Search query is required and cannot be empty')
-            .describe('Search query to find issues'),
+            .describe('Search query with GITHUB SEARCH SYNTAX support. BOOLEAN OPERATORS: "bug AND crash" (both required), "feature OR enhancement" (either term), "error NOT test" (excludes). EXACT PHRASES: "memory leak" (precise matching). GITHUB QUALIFIERS: "is:open label:bug author:username" (native GitHub syntax). COMBINED: Mix boolean logic with qualifiers for precise issue discovery.'),
         owner: z
             .string()
             .min(1)
@@ -1998,26 +2165,26 @@ function registerSearchGitHubIssuesTool(server) {
             .max(50)
             .optional()
             .default(25)
-            .describe('Maximum results (default: 25)'),
+            .describe('Maximum results (default: 25, max: 50)'),
     }, {
-        title: TOOL_NAMES.GITHUB_SEARCH_ISSUES,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_ISSUES],
+        title: TOOL_NAME$1,
+        description: DESCRIPTION$1,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: true,
     }, async (args) => {
         if (!args.query?.trim()) {
-            return createErrorResult$1('Search query is required and cannot be empty', new Error('Invalid query'));
+            return createErrorResult$1('Search query is required and cannot be empty - provide keywords to search for issues', new Error('Invalid query'));
         }
         if (args.query.length > 256) {
-            return createErrorResult$1('Search query is too long. Please limit to 256 characters or less.', new Error('Query too long'));
+            return createErrorResult$1('Search query is too long. Please limit to 256 characters or less - simplify your search terms', new Error('Query too long'));
         }
         try {
             return await searchGitHubIssues(args);
         }
         catch (error) {
-            return createErrorResult$1('Failed to search GitHub issues', error);
+            return createErrorResult$1('GitHub issues search failed - check repository exists and query is valid', error);
         }
     });
 }
@@ -2110,15 +2277,17 @@ function buildGitHubIssuesAPICommand(params) {
     return { command: 'api', args: [apiPath] };
 }
 
+const TOOL_NAME = 'npm_view_package';
+const DESCRIPTION = `Get comprehensive NPM package metadata efficiently. Returns repository URL, exports, dependencies, and version history without needing GitHub searches. Essential for finding package source code and understanding project structure.`;
 function registerNpmViewPackageTool(server) {
-    server.tool(TOOL_NAMES.NPM_VIEW_PACKAGE, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_VIEW_PACKAGE], {
+    server.tool(TOOL_NAME, DESCRIPTION, {
         packageName: z
             .string()
             .min(1, 'Package name is required')
             .describe('NPM package name to analyze. Returns complete package context including exports (critical for GitHub file discovery), repository URL, dependencies, and version history.'),
     }, {
-        title: TOOL_NAMES.NPM_VIEW_PACKAGE,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_VIEW_PACKAGE],
+        title: TOOL_NAME,
+        description: DESCRIPTION,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -2126,17 +2295,17 @@ function registerNpmViewPackageTool(server) {
     }, async (args) => {
         try {
             if (!args.packageName || args.packageName.trim() === '') {
-                return createResult('Package name is required', true);
+                return createResult('Package name is required - provide a valid NPM package name', true);
             }
             // Basic package name validation
             if (!/^[a-z0-9@._/-]+$/.test(args.packageName)) {
-                return createResult('Invalid package name format', true);
+                return createResult('Invalid package name format - use standard NPM naming (e.g., "package-name" or "@scope/package")', true);
             }
             const result = await npmViewPackage(args.packageName);
             return result;
         }
         catch (error) {
-            return createResult(`Failed to get package metadata: ${error.message}`, true);
+            return createResult('Failed to get package metadata - verify package exists on NPM registry', true);
         }
     });
 }
@@ -2194,7 +2363,7 @@ async function npmViewPackage(packageName) {
             return createSuccessResult$1(viewResult);
         }
         catch (error) {
-            return createErrorResult$1('Failed to get npm package metadata', error);
+            return createErrorResult$1('Failed to get npm package metadata - package may not exist or registry unavailable', error);
         }
     });
 }