octocode-mcp 2.3.7 → 2.3.9

package/build/index.js

@@ -168,11 +168,13 @@ function escapeWindowsCmdArg(arg) {
  * Preserves AND search logic by not over-escaping space-separated terms
  */
 function escapeUnixShellArg(arg, isGitHubQuery) {
-    // For GitHub search queries, we need to preserve AND logic
+    // For GitHub search queries, we need to preserve AND logic and quoted phrases
     if (isGitHubQuery) {
-        // If the query contains quotes, preserve them for exact phrase matching
+        // If the query contains quotes, we need to preserve them for GitHub CLI
+        // but escape the entire argument for the shell
         if (arg.includes('"')) {
             // Use single quotes to wrap the entire query while preserving internal quotes
+            // This allows GitHub CLI to see: "quoted phrase" other terms
             return `'${arg.replace(/'/g, "'\"'\"'")}'`;
         }
         // For space-separated terms (AND search), only escape if absolutely necessary
@@ -230,18 +232,30 @@ async function executeGitHubCommand(command, args = [], options = {}) {
     // Get shell configuration
     const shellConfig = getShellConfig(options.windowsShell);
     // Build command with validated prefix and properly escaped arguments
-    // For GitHub search commands, qualifiers like "language:typescript" should not be escaped
-    // Only the main query term (if it contains spaces) needs escaping
+    // For GitHub search commands, we need to distinguish between:
+    // 1. Main query (index 1) - needs special escaping for AND logic
+    // 2. CLI flags (--flag=value) - standard escaping
+    // 3. Search qualifiers (key:value) - minimal escaping
     const escapedArgs = args.map((arg, index) => {
         const isMainQueryArgument = command === 'search' && index === 1;
+        const isCliFlag = arg.startsWith('--');
         const isGitHubQualifier = command === 'search' &&
             index > 1 &&
-            (arg.includes(':') || arg.startsWith('(')) &&
-            !arg.startsWith('--');
-        // Don't escape GitHub search qualifiers - they need to be passed as-is
-        // This includes qualifiers like "language:typescript", "user:microsoft", "org:microsoft"
-        // and complex expressions like "(user:microsoft OR org:microsoft)"
+            !isCliFlag &&
+            (arg.includes(':') || arg.startsWith('('));
+        // CLI flags like --language=javascript, --repo=owner/repo need standard escaping
+        if (isCliFlag) {
+            return escapeShellArg(arg, shellConfig.type, false);
+        }
+        // GitHub search qualifiers need special handling
+        // Most qualifiers can be passed as-is, but those with shell metacharacters need escaping
         if (isGitHubQualifier) {
+            // Check if the qualifier contains shell metacharacters that need escaping
+            if (/[<>&|;`$\\]/.test(arg)) {
+                // Escape qualifiers that contain shell metacharacters like size:<1000, size:>500
+                return escapeShellArg(arg, shellConfig.type, false);
+            }
+            // Safe qualifiers like "language:typescript", "user:microsoft" can be passed as-is
             return arg;
         }
         return escapeShellArg(arg, shellConfig.type, isMainQueryArgument);
@@ -303,6 +317,14 @@ async function executeCommand(fullCommand, type, options = {}, shellConfig) {
                 stderr.trim() !== '';
         if (shouldTreatAsError) {
             const errorType = type === 'npm' ? 'NPM command error' : 'GitHub CLI command error';
+            // Enhanced error messaging for common GitHub issues
+            if (type === 'github' && stderr.includes('404')) {
+                const isRepoNotFound = stderr.includes('Not Found');
+                const enhancedMessage = isRepoNotFound
+                    ? `${stderr}\n\nThis is often due to incorrect repository name. Use github_search_code to find the correct repository.`
+                    : stderr;
+                return createErrorResult(errorType, new Error(enhancedMessage));
+            }
             return createErrorResult(errorType, new Error(stderr));
         }
         // Try to parse stdout as JSON, fallback to string if not possible
@@ -445,24 +467,16 @@ const ERROR_MESSAGES = {
     ISSUE_SEARCH_FAILED: 'Issue search failed - check auth or simplify query',
     PR_SEARCH_FAILED: 'PR search failed - check access and query syntax',
     PACKAGE_SEARCH_FAILED: 'Package search failed - try different keywords',
-    // GitHub CLI errors
-    CLI_INVALID_RESPONSE: 'GitHub CLI invalid response - check "gh version" and update',
-    // Timeout errors
-    SEARCH_TIMEOUT: 'Search timed out - add filters (language, owner) or use specific terms',
     // Query validation errors
     QUERY_TOO_LONG: 'Query too long (max 256 chars) - simplify search terms',
     QUERY_REQUIRED: 'Query required - provide search keywords',
-    EMPTY_QUERY: 'Empty query - try "useState", "authentication", or language:python',
-    QUERY_TOO_LONG_1000: 'Query too long (max 1000 chars) - use key terms like "error handling"',
-    REPO_OR_OWNER_NOT_FOUND: 'Repository/owner not found - check spelling, visibility, and permissions',
-    // Query syntax errors
-    INVALID_QUERY_SYNTAX: 'Invalid syntax - Boolean operators not supported, use quotes for phrases',
-    // Size/format validation errors
-    INVALID_SIZE_FORMAT: 'Invalid size format - use >N, <N, or N..M without quotes',
-    INVALID_SEARCH_SCOPE: 'Invalid scope - use "file" for content, "path" for filenames',
     // API Status check errors
     API_STATUS_CHECK_FAILED: 'API Status Check Failed',
-};
+    // NPM Errors
+    NPM_PACKAGE_NOT_FOUND: 'Package not found on NPM registry',
+    NPM_CONNECTION_FAILED: 'NPM registry connection failed',
+    NPM_CLI_ERROR: 'NPM CLI issue detected',
+    NPM_PERMISSION_ERROR: 'NPM permission issue'};
 const SUGGESTIONS = {
     // Code search suggestions
     CODE_SEARCH_NO_RESULTS: `No results found. Try this progression:
@@ -486,6 +500,31 @@ const SUGGESTIONS = {
 2. Break compound words: "authlib" → "auth"
 3. Search by use case: "user login" vs "authentication"
 4. Try category terms: "framework", "tool", "library"`,
+    // File Content Suggestions
+    FILE_NOT_FOUND_RECOVERY: `Quick fixes:
+• Use github_view_repo_structure to verify path exists
+• Check for typos in file path
+• Try different branch (main/master/develop)`,
+    FILE_TOO_LARGE_RECOVERY: `Alternative strategies:
+• Use github_search_code to search within the file
+• Download directly from GitHub
+• Use github_view_repo_structure to find smaller related files
+• Look for configuration or summary files instead`,
+    // Repository Suggestions
+    REPOSITORY_NOT_FOUND_RECOVERY: `This is often due to incorrect repository name. Steps to resolve:
+1. Use github_search_repositories to find the correct repository
+2. Verify the exact repository name
+3. Check if the repository might have been renamed or moved`,
+    // NPM Suggestions
+    NPM_DISCOVERY_STRATEGIES: `Discovery strategies:
+• Functional search: "validation", "testing", "charts"
+• Ecosystem search: "react", "typescript", "node"
+• Use github_search_repositories for related projects`,
+    NPM_PACKAGE_NAME_ALTERNATIVES: `Try these alternatives:
+• Try with dashes instead of underscores
+• Try without dashes
+• Try scoped package format
+• Use npm_package_search for discovery`,
 };
 // Helper function to get error message with context-specific suggestions
 function getErrorWithSuggestion(options) {
@@ -543,9 +582,348 @@ function createSearchFailedError(type = 'code') {
             return ERROR_MESSAGES.SEARCH_FAILED;
     }
 }
+function createNpmPackageNotFoundError(packageName) {
+    const suggestions = [];
+    if (packageName.includes('_')) {
+        suggestions.push(`• Try with dashes: "${packageName.replace(/_/g, '-')}"`);
+    }
+    if (packageName.includes('-')) {
+        suggestions.push(`• Try without dashes: "${packageName.replace(/-/g, '')}"`);
+    }
+    if (!packageName.includes('/') && packageName.length > 2) {
+        suggestions.push(`• Try scoped format: "@${packageName.slice(0, 3)}/${packageName}"`);
+    }
+    return `${ERROR_MESSAGES.NPM_PACKAGE_NOT_FOUND}: "${packageName}"
+
+${suggestions.length > 0 ? suggestions.join('\n') + '\n\n' : ''}${SUGGESTIONS.NPM_PACKAGE_NAME_ALTERNATIVES}
+
+${SUGGESTIONS.NPM_DISCOVERY_STRATEGIES}`;
+}
+
+/**
+ * Tool relationship map for standardized cross-tool suggestions
+ * Defines how tools connect and when to suggest alternatives
+ */
+const TOOL_NAMES = {
+    API_STATUS_CHECK: 'api_status_check',
+    GITHUB_FETCH_CONTENT: 'github_fetch_content',
+    GITHUB_SEARCH_CODE: 'github_search_code',
+    GITHUB_SEARCH_COMMITS: 'github_search_commits',
+    GITHUB_SEARCH_ISSUES: 'github_search_issues',
+    GITHUB_SEARCH_PULL_REQUESTS: 'github_search_pull_requests',
+    GITHUB_SEARCH_REPOSITORIES: 'github_search_repositories',
+    GITHUB_VIEW_REPO_STRUCTURE: 'github_view_repo_structure',
+    NPM_PACKAGE_SEARCH: 'npm_package_search',
+    NPM_VIEW_PACKAGE: 'npm_view_package',
+};
+const TOOL_RELATIONSHIPS = {
+    [TOOL_NAMES.NPM_PACKAGE_SEARCH]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find repositories by topic or language',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to search for package usage examples',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.NPM_VIEW_PACKAGE,
+                reason: 'to get detailed package information and repository URL',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to explore the package source code structure',
+            },
+        ],
+    },
+    [TOOL_NAMES.NPM_VIEW_PACKAGE]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.NPM_PACKAGE_SEARCH,
+                reason: 'to discover similar packages',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find the repository directly',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to explore repository structure',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_FETCH_CONTENT,
+                reason: 'to read specific files like README or package.json',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to find usage examples',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.NPM_PACKAGE_SEARCH,
+                reason: 'if searching for packages or libraries',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to search within repository contents',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to explore repository contents',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_ISSUES,
+                reason: 'to check open issues and discussions',
+            },
+            {
+                tool: TOOL_NAMES.NPM_VIEW_PACKAGE,
+                reason: 'if repository is an NPM package',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_SEARCH_CODE]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.NPM_PACKAGE_SEARCH,
+                reason: 'if searching for package implementations',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find repositories by topic',
+            },
+            {
+                tool: TOOL_NAMES.API_STATUS_CHECK,
+                reason: 'if no results (might be private repos)',
+                condition: 'no_results',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_FETCH_CONTENT,
+                reason: 'to view full file contents',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to explore repository structure',
+            },
+        ],
+        prerequisites: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to verify file paths before searching',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_FETCH_CONTENT]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to verify correct file path',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to search for similar files',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to explore related files',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to find usage examples',
+            },
+        ],
+        prerequisites: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to verify file exists and get correct path',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find the correct repository',
+            },
+            {
+                tool: TOOL_NAMES.API_STATUS_CHECK,
+                reason: 'if access denied (check authentication)',
+                condition: 'access_denied',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_FETCH_CONTENT,
+                reason: 'to read specific files',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to search within the repository',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_SEARCH_COMMITS]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find repositories first',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_ISSUES,
+                reason: 'to find related discussions',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_FETCH_CONTENT,
+                reason: 'to view files changed in commits',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to find current implementation',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_SEARCH_ISSUES]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS,
+                reason: 'to find related PRs',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find the repository first',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS,
+                reason: 'to find solutions or implementations',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to find related code',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_ISSUES,
+                reason: 'to find related issues',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_COMMITS,
+                reason: 'to find related commits',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_FETCH_CONTENT,
+                reason: 'to view PR changes',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to find current implementation',
+            },
+        ],
+    },
+    [TOOL_NAMES.API_STATUS_CHECK]: {
+        fallbackTools: [],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to search accessible repositories',
+            },
+            {
+                tool: TOOL_NAMES.NPM_PACKAGE_SEARCH,
+                reason: 'to search public packages',
+            },
+        ],
+    },
+};
+/**
+ * Get tool suggestions based on current context
+ */
+function getToolSuggestions(currentTool, context) {
+    const relationships = TOOL_RELATIONSHIPS[currentTool];
+    if (!relationships) {
+        return { fallback: [], nextSteps: [], prerequisites: [] };
+    }
+    // Filter fallback tools based on context
+    const fallback = relationships.fallbackTools.filter(item => {
+        if (!item.condition)
+            return true;
+        switch (item.condition) {
+            case 'no_results':
+                return context.errorType === 'no_results';
+            case 'access_denied':
+                return context.errorType === 'access_denied';
+            default:
+                return true;
+        }
+    });
+    // Return next steps only if operation was successful
+    const nextSteps = context.hasResults ? relationships.nextSteps : [];
+    return {
+        fallback,
+        nextSteps,
+        prerequisites: relationships.prerequisites || [],
+    };
+}
+
+/**
+ * Shared validation utilities for MCP tools
+ * Centralized validation logic to reduce duplication across tools
+ */
+/**
+ * Extracts owner/repo from various query formats
+ * Handles: owner/repo, https://github.com/owner/repo, github.com/owner/repo
+ */
+/**
+ * Creates a standardized tool suggestion message
+ */
+function createToolSuggestion(currentTool, suggestedTools) {
+    if (suggestedTools.length === 0) {
+        return '';
+    }
+    const suggestions = suggestedTools
+        .map(({ tool, reason }) => `• Use ${tool} ${reason}`)
+        .join('\n');
+    return `\n\nCurrent tool: ${currentTool}\nAlternative tools:\n${suggestions}`;
+}
 
 const API_STATUS_CHECK_TOOL_NAME = 'apiStatusCheck';
-const DESCRIPTION$9 = `Check GitHub and NPM authentication status. Returns connected status and GitHub organizations for accessing private repositories. No parameters required.`;
+const DESCRIPTION$9 = `Verify API connections and discover available organizations. FIRST STEP for private repository research.
+
+AUTHENTICATION VERIFICATION:
+- Check GitHub and NPM CLI authentication status
+- Troubleshoot access issues before extensive searches
+- Verify API connectivity and permissions
+
+ORGANIZATION DISCOVERY:
+- List available GitHub organizations for scoped searches  
+- Identify accessible private repositories
+- Guide repository search strategy based on permissions
+
+WORKFLOW OPTIMIZATION:
+- Run first when dealing with private/organizational repositories
+- Prevents access errors in subsequent tool usage
+- Informs search scope and strategy decisions
+- Essential for comprehensive organizational research`;
 // Helper function to parse execution results with proper typing
 function parseExecResult(result) {
     if (!result.isError && result.content?.[0]?.text) {
@@ -651,6 +1029,19 @@ function registerApiStatusCheckTool(server) {
                 }
                 npmConnected = false;
             }
+            const { nextSteps } = getToolSuggestions(TOOL_NAMES.API_STATUS_CHECK, {
+                hasResults: true,
+            });
+            const hints = [
+                'Use user organizations to search private repositories when requested - verify access by checking query and repository structure',
+            ];
+            // Add tool suggestions as hints
+            if (nextSteps.length > 0) {
+                hints.push('Next steps:');
+                nextSteps.forEach(({ tool, reason }) => {
+                    hints.push(`- ${tool}: ${reason}`);
+                });
+            }
             return createResult({
                 data: {
                     login: {
@@ -662,55 +1053,77 @@ function registerApiStatusCheckTool(server) {
                             connected: npmConnected,
                             registry: registry || 'https://registry.npmjs.org/',
                         },
-                        hints: [
-                            'Use user organizations to search private repositories when requested - verify access by checking query and repository structure',
-                        ],
+                        hints,
                     },
                 },
             });
         }
         catch (error) {
+            const { nextSteps } = getToolSuggestions(TOOL_NAMES.API_STATUS_CHECK, {
+                });
+            const toolSuggestions = createToolSuggestion(TOOL_NAMES.API_STATUS_CHECK, nextSteps);
             return createResult({
-                error: `${ERROR_MESSAGES.API_STATUS_CHECK_FAILED}\nError: ${error instanceof Error ? error.message : 'Unknown error'}\n\nThis usually indicates a system configuration issue. Please verify GitHub CLI and NPM are properly installed.`,
+                error: getErrorWithSuggestion({
+                    baseError: [
+                        ERROR_MESSAGES.API_STATUS_CHECK_FAILED,
+                        `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        '',
+                        'This usually indicates a system configuration issue. Please verify GitHub CLI and NPM are properly installed.',
+                    ],
+                    suggestion: toolSuggestions,
+                }),
             });
         }
     });
 }
 
-const GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME = 'githubViewRepoStructure';
-const DESCRIPTION$8 = `Explore repository structure and navigate directories. Auto-detects branches and provides file/folder listings with size information. Parameters: owner (required - GitHub username/org), repo (required - repository name), branch (required), path (optional).`;
-function registerViewRepositoryStructureTool(server) {
-    server.registerTool(GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME, {
+const GITHUB_GET_FILE_CONTENT_TOOL_NAME = 'githubGetFileContent';
+const DESCRIPTION$8 = `Access GitHub file content for implementation analysis. USE AFTER repository structure validation.
+
+IMPLEMENTATION ANALYSIS:
+- Examine configuration files, documentation, key source code
+- Understand actual implementations and patterns
+- Extract technical details and architecture decisions
+
+VALIDATION REQUIREMENTS:
+- ALWAYS verify repository structure first with githubViewRepoStructure
+- Confirm file paths exist before accessing
+- Navigate from known structure to specific files
+
+CONTENT CAPABILITIES:
+- Handles text files up to 300KB efficiently
+- Automatic branch fallback (main/master)
+- Provides decoded content with metadata
+- Optimized for code analysis workflows`;
+function registerFetchGitHubFileContentTool(server) {
+    server.registerTool(GITHUB_GET_FILE_CONTENT_TOOL_NAME, {
         description: DESCRIPTION$8,
         inputSchema: {
             owner: z
                 .string()
                 .min(1)
                 .max(100)
-                .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/, 'Invalid GitHub username/org format')
-                .describe(`Repository owner/org name (e.g., 'microsoft', 'google', NOT 'microsoft/vscode')`),
+                .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/)
+                .describe(`Repository owner/organization name (e.g., 'facebook', 'microsoft'). Do NOT include repository name here.`),
             repo: z
                 .string()
                 .min(1)
                 .max(100)
-                .regex(/^[a-zA-Z0-9._-]+$/, 'Invalid repository name format')
-                .describe('Repository name (case-sensitive)'),
+                .regex(/^[a-zA-Z0-9._-]+$/)
+                .describe(`Repository name only (e.g., 'react', 'vscode'). Do NOT include owner/org prefix.`),
             branch: z
                 .string()
                 .min(1)
                 .max(255)
-                .regex(/^[^\s]+$/, 'Branch name cannot contain spaces')
-                .describe('Branch name. Falls back to default branch if not found'),
-            path: z
+                .regex(/^[^\s]+$/)
+                .describe(`Branch name (e.g., 'main', 'master'). Tool will automatically try 'main' and 'master' if specified branch is not found.`),
+            filePath: z
                 .string()
-                .optional()
-                .default('')
-                .refine(path => !path.includes('..'), 'Path traversal not allowed')
-                .refine(path => path.length <= 500, 'Path too long')
-                .describe('Directory path within repository. Leave empty for root.'),
+                .min(1)
+                .describe(`File path from repository root (e.g., 'src/index.js', 'README.md', 'docs/api.md'). Do NOT start with slash.`),
         },
         annotations: {
-            title: 'GitHub Repository Explorer',
+            title: 'GitHub File Content - Direct Access',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
@@ -718,63 +1131,28 @@ function registerViewRepositoryStructureTool(server) {
         },
     }, async (args) => {
         try {
-            const result = await viewRepositoryStructure(args);
+            const result = await fetchGitHubFileContent(args);
             return result;
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
             return createResult({
-                error: `Failed to explore repository. ${errorMessage}. Verify repository exists and is accessible`,
+                error: 'Failed to fetch file. Verify path with github_get_contents first',
             });
         }
     });
 }
-/**
- * Views the structure of a GitHub repository at a specific path.
- * Optimized for code analysis workflows with smart defaults and clear errors.
- */
-async function viewRepositoryStructure(params) {
-    const cacheKey = generateCacheKey('gh-repo-structure', params);
+async function fetchGitHubFileContent(params) {
+    const cacheKey = generateCacheKey('gh-file-content', params);
     return withCache(cacheKey, async () => {
-        const { owner, repo, branch, path = '' } = params;
+        const { owner, repo, branch, filePath } = params;
         try {
-            // Clean up path
-            const cleanPath = path.startsWith('/') ? path.substring(1) : path;
-            // Try the requested branch first, then fallback to main/master
-            const branchesToTry = await getSmartBranchFallback(owner, repo, branch);
-            let items = [];
-            let usedBranch = branch;
-            let lastError = null;
-            let attemptCount = 0;
-            const maxAttempts = branchesToTry.length;
-            const triedBranches = [];
-            for (const tryBranch of branchesToTry) {
-                if (attemptCount >= maxAttempts)
-                    break;
-                attemptCount++;
-                triedBranches.push(tryBranch);
-                try {
-                    const apiPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${tryBranch}`;
-                    const result = await executeGitHubCommand('api', [apiPath], {
-                        cache: false,
-                    });
-                    if (!result.isError) {
-                        const execResult = JSON.parse(result.content[0].text);
-                        const apiItems = execResult.result;
-                        items = Array.isArray(apiItems) ? apiItems : [apiItems];
-                        usedBranch = tryBranch;
-                        break;
-                    }
-                    else {
-                        lastError = new Error(result.content[0].text);
-                    }
-                }
-                catch (error) {
-                    lastError = error instanceof Error ? error : new Error(String(error));
-                    continue;
-                }
-            }
-            if (items.length === 0) {
+            // Try to fetch file content directly
+            const apiPath = `/repos/${owner}/${repo}/contents/${filePath}`;
+            const result = await executeGitHubCommand('api', [apiPath], {
+                cache: false,
+            });
+            if (result.isError) {
+                const errorMsg = result.content[0].text;
                 // Check repository existence only after content fetch fails
                 const repoCheckResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
                     cache: false,
@@ -783,7 +1161,7 @@ async function viewRepositoryStructure(params) {
                     const repoErrorMsg = repoCheckResult.content[0].text;
                     if (repoErrorMsg.includes('404')) {
                         return createResult({
-                            error: `Repository "${owner}/${repo}" not found. It might have been deleted, renamed, or made private. Use github_search_code to find current location.`,
+                            error: `Repository "${owner}/${repo}" not found. This is often due to incorrect repository name. Steps to resolve:\n1. Use github_search_code with query="${filePath.split('/').pop()}" owner="${owner}" to find the correct repository\n2. Verify the exact repository name\n3. Check if the repository might have been renamed or moved`,
                         });
                     }
                     else if (repoErrorMsg.includes('403')) {
@@ -792,277 +1170,102 @@ async function viewRepositoryStructure(params) {
                         });
                     }
                 }
-                const errorMsg = lastError?.message || 'Unknown error';
-                if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
-                    if (path) {
-                        const searchSuggestion = await suggestPathSearchFallback(owner, path);
-                        return createResult({
-                            error: `Path "${path}" not found in any branch (tried: ${triedBranches.join(', ')}).${searchSuggestion}`,
-                        });
-                    }
-                    else {
-                        return createResult({
-                            error: `Repository "${owner}/${repo}" structure not accessible. Repository might be empty, private, or you might not have sufficient permissions. Use github_search_code with owner="${owner}" to find accessible repositories.`,
+                // Try fallback branches if original branch fails
+                if (errorMsg.includes('404') &&
+                    branch !== 'main' &&
+                    branch !== 'master') {
+                    const fallbackBranches = ['main', 'master'];
+                    const triedBranches = [branch];
+                    for (const fallbackBranch of fallbackBranches) {
+                        if (triedBranches.includes(fallbackBranch))
+                            continue;
+                        triedBranches.push(fallbackBranch);
+                        const fallbackPath = `/repos/${owner}/${repo}/contents/${filePath}?ref=${fallbackBranch}`;
+                        const fallbackResult = await executeGitHubCommand('api', [fallbackPath], {
+                            cache: false,
                         });
+                        if (!fallbackResult.isError) {
+                            return await processFileContent(fallbackResult, owner, repo, fallbackBranch, filePath);
+                        }
                     }
+                    return createResult({
+                        error: `File not found in any common branches (tried: ${triedBranches.join(', ')}). File might have been moved or deleted. Use github_search_code to find current location.`,
+                    });
                 }
-                else if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
+                // Handle common errors with more context
+                if (errorMsg.includes('404')) {
+                    const searchSuggestion = await suggestCodeSearchFallback(owner, filePath);
                     return createResult({
-                        error: `Access denied to "${owner}/${repo}". Repository exists but might be private/archived. Use api_status_check to verify permissions, or github_search_code with owner="${owner}" to find accessible repositories.`,
+                        error: `File "${filePath}" not found in branch "${branch}".
+
+Quick fixes:
+• Use github_view_repo_structure to verify path exists
+• Check for typos in file path
+• Try different branch (main/master/develop)${searchSuggestion}
+
+Alternative strategies:
+• Use github_search_code with query="filename:${filePath.split('/').pop()}" owner="${owner}"
+• Use github_search_code with query="path:${filePath}" to find similar paths`,
+                    });
+                }
+                else if (errorMsg.includes('403')) {
+                    return createResult({
+                        error: `Access denied to "${filePath}" in "${owner}/${repo}".
+
+Possible causes & solutions:
+• Private repository: use api_status_check to verify permissions
+• File in private directory: check repository access level
+• Rate limiting: wait 5-10 minutes and retry
+• Authentication: run gh auth login
+
+Alternative approaches:
+• Use github_search_code with query="path:${filePath}" owner="${owner}"
+• Use github_view_repo_structure to explore accessible paths
+• Check repository on GitHub.com for public access`,
+                    });
+                }
+                else if (errorMsg.includes('maxBuffer') ||
+                    errorMsg.includes('stdout maxBuffer length exceeded')) {
+                    return createResult({
+                        error: `File "${filePath}" is too large (>300KB).
+
+Alternative strategies:
+• Use github_search_code to search within the file
+• Download directly from: https://github.com/${owner}/${repo}/blob/${branch}/${filePath}
+• Use github_view_repo_structure to find smaller related files
+• Look for configuration or summary files instead`,
                     });
                 }
                 else {
-                    const searchSuggestion = path
-                        ? await suggestPathSearchFallback(owner, path)
-                        : '';
+                    const searchSuggestion = await suggestCodeSearchFallback(owner, filePath);
                     return createResult({
-                        error: `Failed to access "${owner}/${repo}": ${errorMsg}. Check network connection and repository permissions.${searchSuggestion}`,
+                        error: `Failed to fetch "${filePath}": ${errorMsg}
+
+Troubleshooting steps:
+1. Verify repository exists: github_view_repo_structure
+2. Check network connection and GitHub status
+3. Verify authentication: gh auth status
+4. Try different branch names${searchSuggestion}
+
+Recovery strategies:
+• Use github_search_code for content discovery
+• Try github_search_repos to find similar repositories
+• Check file on GitHub.com: https://github.com/${owner}/${repo}/blob/${branch}/${filePath}`,
                     });
                 }
             }
-            // Limit total items to 100 for efficiency
-            const limitedItems = items.slice(0, 100);
-            // Sort: directories first, then alphabetically
-            limitedItems.sort((a, b) => {
-                if (a.type !== b.type) {
-                    return a.type === 'dir' ? -1 : 1;
-                }
-                return a.name.localeCompare(b.name);
-            });
-            // Create simplified, token-efficient structure
-            const files = limitedItems
-                .filter(item => item.type === 'file')
-                .map(item => ({
-                name: item.name,
-                size: item.size,
-                url: item.path, // Use path for fetching
-            }));
-            const folders = limitedItems
-                .filter(item => item.type === 'dir')
-                .map(item => ({
-                name: item.name,
-                url: item.path, // Use path for browsing
-            }));
-            return createResult({
-                data: {
-                    repository: `${owner}/${repo}`,
-                    branch: usedBranch,
-                    path: cleanPath || '/',
-                    githubBasePath: `https://api.github.com/repos/${owner}/${repo}/contents/`,
-                    files: {
-                        count: files.length,
-                        files: files,
-                    },
-                    folders: {
-                        count: folders.length,
-                        folders: folders,
-                    },
-                },
-            });
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            return createResult({
-                error: `Failed to access repository "${owner}/${repo}": ${errorMessage}. Verify repository name, permissions, and network connection.`,
-            });
-        }
-    });
-}
-/**
- * Smart branch detection with automatic fallback to common branch names.
- * Now includes more comprehensive branch detection and better error handling.
- */
-async function getSmartBranchFallback(owner, repo, requestedBranch) {
-    const branches = new Set([requestedBranch]);
-    try {
-        // Try to get repository info to find default branch
-        const repoInfoResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
-            cache: false,
-        });
-        if (!repoInfoResult.isError) {
-            const execResult = JSON.parse(repoInfoResult.content[0].text);
-            const repoData = execResult.result;
-            const defaultBranch = repoData.default_branch;
-            if (defaultBranch) {
-                branches.add(defaultBranch);
-            }
-        }
-    }
-    catch {
-        // If we can't get repo info, proceed with standard fallbacks
-    }
-    // Add only main/master as fallback branches
-    const commonBranches = ['main', 'master'];
-    commonBranches.forEach(branch => branches.add(branch));
-    // Convert Set back to array, with requested branch first
-    const branchesArray = Array.from(branches);
-    branchesArray.sort((a, b) => {
-        if (a === requestedBranch)
-            return -1;
-        if (b === requestedBranch)
-            return 1;
-        return 0;
-    });
-    return branchesArray;
-}
-// Helper function to suggest path search strategy
-async function suggestPathSearchFallback(owner, path) {
-    try {
-        // Extract last path segment and try to find in same organization
-        const pathSegment = path.split('/').pop() || path;
-        const searchResult = await executeGitHubCommand('api', [
-            `/search/code?q=${encodeURIComponent(pathSegment)}+in:path+org:${owner}`,
-        ], { cache: false });
-        if (!searchResult.isError) {
-            const results = JSON.parse(searchResult.content[0].text);
-            if (results.total_count > 0) {
-                const firstMatch = results.items[0];
-                return ` Directory might be in ${firstMatch.repository.full_name}. Try these searches:\n1. github_search_code with query="${pathSegment}" owner="${owner}"\n2. github_search_code with query="path:${path}" owner="${owner}"`;
-            }
-        }
-    }
-    catch {
-        // Fallback to generic message if search fails
-    }
-    return ` Try these searches:\n1. github_search_code with query="${path.split('/').pop()}" owner="${owner}"\n2. github_search_code with query="path:${path}"`;
-}
-
-const GITHUB_GET_FILE_CONTENT_TOOL_NAME = 'githubGetFileContent';
-const DESCRIPTION$7 = `Fetch file content from GitHub repositories. Use ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME} first to explore repository structure and find exact file paths. Supports automatic branch fallback (main/master) and handles files up to 300KB. Parameters: owner (required - GitHub username/org), repo (required - repository name), branch (required), filePath (required).`;
-function registerFetchGitHubFileContentTool(server) {
-    server.registerTool(GITHUB_GET_FILE_CONTENT_TOOL_NAME, {
-        description: DESCRIPTION$7,
-        inputSchema: {
-            owner: z
-                .string()
-                .min(1)
-                .max(100)
-                .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/)
-                .describe(`Repository owner/org name (e.g., 'microsoft', 'google', NOT 'microsoft/vscode')`),
-            repo: z
-                .string()
-                .min(1)
-                .max(100)
-                .regex(/^[a-zA-Z0-9._-]+$/)
-                .describe(`Repository name only (e.g., 'vscode', 'react', NOT 'microsoft/vscode')`),
-            branch: z
-                .string()
-                .min(1)
-                .max(255)
-                .regex(/^[^\s]+$/)
-                .describe(`Branch name. Falls back to main/master if not found`),
-            filePath: z
-                .string()
-                .min(1)
-                .describe(`Exact file path from repo root (e.g., src/index.js, README.md)`),
-        },
-        annotations: {
-            title: 'GitHub File Content - Direct Access',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: true,
-        },
-    }, async (args) => {
-        try {
-            const result = await fetchGitHubFileContent(args);
-            return result;
-        }
-        catch (error) {
-            return createResult({
-                error: 'Failed to fetch file. Verify path with github_get_contents first',
-            });
-        }
-    });
-}
-async function fetchGitHubFileContent(params) {
-    const cacheKey = generateCacheKey('gh-file-content', params);
-    return withCache(cacheKey, async () => {
-        const { owner, repo, branch, filePath } = params;
-        try {
-            // Try to fetch file content directly
-            const apiPath = `/repos/${owner}/${repo}/contents/${filePath}`;
-            const result = await executeGitHubCommand('api', [apiPath], {
-                cache: false,
-            });
-            if (result.isError) {
-                const errorMsg = result.content[0].text;
-                // Check repository existence only after content fetch fails
-                const repoCheckResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
-                    cache: false,
-                });
-                if (repoCheckResult.isError) {
-                    const repoErrorMsg = repoCheckResult.content[0].text;
-                    if (repoErrorMsg.includes('404')) {
-                        return createResult({
-                            error: `Repository "${owner}/${repo}" not found. It might have been deleted, renamed, or made private. Use github_search_code to find current location.`,
-                        });
-                    }
-                    else if (repoErrorMsg.includes('403')) {
-                        return createResult({
-                            error: `Repository "${owner}/${repo}" exists but access is denied. Repository might be private or archived. Use api_status_check to verify permissions.`,
-                        });
-                    }
-                }
-                // Try fallback branches if original branch fails
-                if (errorMsg.includes('404') &&
-                    branch !== 'main' &&
-                    branch !== 'master') {
-                    const fallbackBranches = ['main', 'master'];
-                    const triedBranches = [branch];
-                    for (const fallbackBranch of fallbackBranches) {
-                        if (triedBranches.includes(fallbackBranch))
-                            continue;
-                        triedBranches.push(fallbackBranch);
-                        const fallbackPath = `/repos/${owner}/${repo}/contents/${filePath}?ref=${fallbackBranch}`;
-                        const fallbackResult = await executeGitHubCommand('api', [fallbackPath], {
-                            cache: false,
-                        });
-                        if (!fallbackResult.isError) {
-                            return await processFileContent(fallbackResult, owner, repo, fallbackBranch, filePath);
-                        }
-                    }
-                    return createResult({
-                        error: `File not found in any common branches (tried: ${triedBranches.join(', ')}). File might have been moved or deleted. Use github_search_code to find current location.`,
-                    });
-                }
-                // Handle common errors with more context
-                if (errorMsg.includes('404')) {
-                    const searchSuggestion = await suggestCodeSearchFallback(owner, filePath);
-                    return createResult({
-                        error: `File "${filePath}" not found in branch "${branch}". Use github_view_repo_structure to verify path.${searchSuggestion}`,
-                    });
-                }
-                else if (errorMsg.includes('403')) {
-                    return createResult({
-                        error: `Access denied to "${filePath}" in "${owner}/${repo}". Repository or file might be private/archived. Use api_status_check to verify permissions, or github_search_code with query="path:${filePath}" owner="${owner}" to find in accessible repositories.`,
-                    });
-                }
-                else if (errorMsg.includes('maxBuffer') ||
-                    errorMsg.includes('stdout maxBuffer length exceeded')) {
-                    return createResult({
-                        error: `File "${filePath}" is too large (>300KB). Use github_search_code with query="path:${filePath}" to search within the file or download directly from GitHub.`,
-                    });
-                }
-                else {
-                    const searchSuggestion = await suggestCodeSearchFallback(owner, filePath);
-                    return createResult({
-                        error: `Failed to fetch "${filePath}". Error: ${errorMsg}. Verify repository name, branch, and file path.${searchSuggestion}`,
-                    });
-                }
-            }
-            return await processFileContent(result, owner, repo, branch, filePath);
-        }
-        catch (error) {
-            const errorMessage = error.message;
-            if (errorMessage.includes('maxBuffer') ||
-                errorMessage.includes('stdout maxBuffer length exceeded')) {
-                return createResult({
-                    error: `File "${filePath}" is too large (>300KB). Use github_search_code to search within the file or download directly from GitHub.`,
-                });
-            }
-            return createResult({
-                error: `Unexpected error fetching "${filePath}": ${errorMessage}. Check network connection and try again.`,
+            return await processFileContent(result, owner, repo, branch, filePath);
+        }
+        catch (error) {
+            const errorMessage = error.message;
+            if (errorMessage.includes('maxBuffer') ||
+                errorMessage.includes('stdout maxBuffer length exceeded')) {
+                return createResult({
+                    error: `File "${filePath}" is too large (>300KB). Use github_search_code to search within the file or download directly from GitHub.`,
+                });
+            }
+            return createResult({
+                error: `Unexpected error fetching "${filePath}": ${errorMessage}. Check network connection and try again.`,
             });
         }
     });
@@ -1146,55 +1349,73 @@ async function suggestCodeSearchFallback(owner, filePath) {
 }
 
 const GITHUB_SEARCH_CODE_TOOL_NAME = 'githubSearchCode';
-const DESCRIPTION$6 = `Search code across GitHub repositories using GitHub's code search API.
-
-Search Syntax (all terms must be present with AND logic):
-- Multiple words: react lifecycle → finds files with BOTH "react" AND "lifecycle" (separate words)
-- Exact phrases: "error handling" → finds exact phrase "error handling" (quoted phrase)
-- Mixed: "async function" timeout → finds exact phrase "async function" AND word "timeout"
-- Complex: useState useEffect "custom hook" → finds "useState" AND "useEffect" AND exact phrase "custom hook"
-- Advanced: authentication authorization "jwt token" → finds "authentication" AND "authorization" AND exact phrase "jwt token"
-- Framework: "React.Component" "componentDidMount" → finds both exact phrases in same file
-
-Key difference: Quotes create exact phrases, no quotes = individual words (all must be present).
-Start with 1-2 terms, add more to narrow results. Use filters for precision.`;
+const DESCRIPTION$7 = `Search code across GitHub repositories using GitHub's code search API via GitHub CLI.
+
+SEARCH STRATEGY FOR BEST RESULTS:
+
+TERM OPTIMIZATION (IMPORTANT):
+- BEST: Single terms for maximum coverage and relevance
+- GOOD: 2 terms when you need both to be present  
+- RESTRICTIVE: 3+ terms - very specific but may miss relevant results
+- Example: "useState" (best coverage) vs "react hook useState" (specific but restrictive)
+
+MULTI-SEARCH STRATEGY:
+- Use SEPARATE searches for different aspects instead of complex single queries
+- Example: Search "authentication" separately, then "login" separately
+- Separate searches provide broader coverage than restrictive AND logic
+
+Search Logic:
+- Multiple terms = ALL must be present (AND logic) - very restrictive
+- Single terms = maximum results and coverage
+- Quoted phrases = exact phrase matching
+- Mixed queries: "exact phrase" additional_term (phrase + term)
+
+Quote Usage:
+- Single terms: NO quotes (useState, authentication)
+- Multi-word phrases: WITH quotes ("error handling", "user authentication")
+- Mixed queries: "exact phrase" single_term another_term
+
+Filter Usage:
+- All filters use GitHub CLI flags (--language, --owner, --repo, etc.)
+- Combine filters to narrow scope: language + owner, repo + filename
+- Never use filters on exploratory searches - use to refine when too many results`;
 function registerGitHubSearchCodeTool(server) {
     server.registerTool(GITHUB_SEARCH_CODE_TOOL_NAME, {
-        description: DESCRIPTION$6,
+        description: DESCRIPTION$7,
         inputSchema: {
             query: z
                 .string()
                 .min(1)
-                .describe('Search query with AND logic between terms. Multiple words require ALL to be present. Use quotes for exact phrases. Examples: react lifecycle (both words), "error handling" (exact phrase), async await "try catch" (words + phrase), "function definition" variable scope (phrase + words)'),
+                .describe('Search query with AND logic between terms. OPTIMIZATION: Single terms give best coverage, 2 terms when both needed, 3+ terms very restrictive. Multiple words require ALL to be present. Use quotes for exact phrases. Examples: "useState" (best coverage), "error handling" (exact phrase), "react hook useState" (specific but restrictive).'),
             language: z
                 .string()
                 .optional()
-                .describe('Programming language filter (javascript, python, typescript, go, etc). Narrows search to specific language files. Use for language-specific searches.'),
+                .describe('Programming language filter. Uses --language CLI flag. Narrows search to specific language files. Use for language-specific searches.'),
             owner: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Repository owner or organization name(s) to search within. Format: "microsoft" or ["facebook", "google"]. Drastically narrows search scope. Do NOT use owner/repo format.'),
+                .describe('Repository owner/organization name(s) to search within (e.g., "facebook", ["google", "microsoft"]). Uses --owner CLI flag for organization-wide search. Can be combined with repo parameter for specific repository search. Do NOT use owner/repo format - just the organization/username.'),
             repo: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Filter on specific repository(ies). Format: "owner/repo" or ["microsoft/vscode", "facebook/react"]. Use for repository-specific searches.'),
+                .describe('Filter on specific repository(ies). Uses --repo CLI flag. Two usage patterns: (1) Use with owner parameter - provide just repo name (e.g., owner="facebook", repo="react" → --repo=facebook/react), or (2) Use alone - provide full "owner/repo" format (e.g., "facebook/react" → --repo=facebook/react).'),
             filename: z
                 .string()
                 .optional()
-                .describe('Target specific filename or pattern. Examples: "package.json", "*.test.js", "Dockerfile". Use for file-specific searches.'),
+                .describe('Target specific filename or pattern. Uses --filename CLI flag. Use for file-specific searches.'),
             extension: z
                 .string()
                 .optional()
-                .describe('File extension filter (js, py, ts, go, etc). Alternative to language parameter. Examples: "js", "py", "tsx".'),
+                .describe('File extension filter. Uses --extension CLI flag. Alternative to language parameter.'),
             match: z
-                .union([z.enum(['file', 'path']), z.array(z.enum(['file', 'path']))])
+                .enum(['file', 'path'])
                 .optional()
-                .describe('Search scope: "file" for file content (default), "path" for filenames/paths, or ["file", "path"] for both. Controls where to search for terms.'),
+                .describe('Search scope: "file" for file content (default), "path" for filenames/paths. Uses --match CLI flag. Single value only - multiple scopes not supported by GitHub CLI.'),
             size: z
                 .string()
                 .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid size format. Use: ">10", ">=5", "<100", "<=50", "10..100", or exact number "50"')
                 .optional()
-                .describe('File size filter in KB. Format: ">10" (larger than), ">=5" (at least), "<100" (smaller than), "<=50" (at most), "10..50" (range), "25" (exact). Examples from docs: ">10", "10..50", "<100"'),
+                .describe('File size filter in KB. Uses --size CLI flag. Format: ">N" (larger than), "<N" (smaller than), "N..M" (range), "N" (exact).'),
             limit: z
                 .number()
                 .int()
@@ -1213,11 +1434,6 @@ function registerGitHubSearchCodeTool(server) {
         },
     }, async (args) => {
         try {
-            // Validate parameter combinations
-            const validationError = validateSearchParameters(args);
-            if (validationError) {
-                return createResult({ error: validationError });
-            }
             const result = await searchGitHubCode(args);
             if (result.isError) {
                 return result;
@@ -1252,45 +1468,79 @@ function registerGitHubSearchCodeTool(server) {
     });
 }
 /**
- * Handles various search errors and returns a formatted CallToolResult.
+ * Handles various search errors and returns a formatted CallToolResult with smart fallbacks.
  */
 function handleSearchError(errorMessage) {
-    // Common GitHub search errors with helpful suggestions
-    if (errorMessage.includes('JSON')) {
+    // Rate limit with smart timing guidance
+    if (errorMessage.includes('rate limit') || errorMessage.includes('403')) {
         return createResult({
-            error: ERROR_MESSAGES.CLI_INVALID_RESPONSE,
+            error: `GitHub API rate limit reached. Try again in 5-10 minutes, or use these strategies:
+• Search fewer terms per query
+• Use owner/repo filters to narrow scope
+• Try npm package search for package-related queries
+• Use separate searches instead of complex queries`,
         });
     }
-    if (errorMessage.includes('authentication')) {
+    // Authentication with clear next steps
+    if (errorMessage.includes('authentication') || errorMessage.includes('401')) {
         return createResult({
-            error: createAuthenticationError(),
+            error: `GitHub authentication required. Fix with:
+1. Run: gh auth login
+2. Verify access: gh auth status
+3. For private repos: use api_status_check to verify org access`,
         });
     }
-    if (errorMessage.includes('rate limit')) {
+    // Network/timeout with fallback suggestions
+    if (errorMessage.includes('timed out') || errorMessage.includes('network')) {
         return createResult({
-            error: createRateLimitError(true),
-        });
-    }
-    if (errorMessage.includes('timed out')) {
-        return createResult({
-            error: ERROR_MESSAGES.SEARCH_TIMEOUT,
+            error: `Network timeout. Try these alternatives:
+• Reduce search scope with owner or language filters
+• Use github_search_repos to find repositories first
+• Try npm package search for package discovery
+• Check network connection and retry`,
         });
     }
+    // Invalid query with specific fixes
     if (errorMessage.includes('validation failed') ||
         errorMessage.includes('Invalid query')) {
         return createResult({
-            error: ERROR_MESSAGES.INVALID_QUERY_SYNTAX,
+            error: `Invalid search query. Common fixes:
+• Remove special characters: ()[]{}*?^$|.\\
+• Use quotes only for exact phrases: "error handling"
+• Avoid escaped quotes: use term instead of "term"
+• Try broader terms: "react" instead of "React.Component"`,
         });
     }
+    // Repository not found with discovery suggestions
     if (errorMessage.includes('repository not found') ||
         errorMessage.includes('owner not found')) {
         return createResult({
-            error: ERROR_MESSAGES.REPO_OR_OWNER_NOT_FOUND,
+            error: `Repository/owner not found. Discovery strategies:
+• Use github_search_repos to find correct names
+• Check for typos in owner/repo names
+• Try without owner filter for broader search
+• Use npm package search if looking for packages`,
+        });
+    }
+    // JSON parsing with system guidance
+    if (errorMessage.includes('JSON')) {
+        return createResult({
+            error: `GitHub CLI response parsing failed. System issue - try:
+• Update GitHub CLI: gh extension upgrade
+• Retry in a few moments
+• Use github_search_repos as alternative
+• Check gh auth status for authentication`,
         });
     }
-    // Generic fallback with guidance
+    // Generic fallback with progressive strategy
     return createResult({
-        error: `Code search failed: ${errorMessage}\n${SUGGESTIONS.SIMPLIFY_QUERY}`,
+        error: `Code search failed: ${errorMessage}
+
+Progressive recovery strategy:
+1. Try broader search terms
+2. Use github_search_repos to find repositories
+3. Use npm package search for package-related queries
+4. Check github CLI status: gh auth status`,
     });
 }
 /**
@@ -1308,6 +1558,10 @@ function transformToOptimizedFormat$1(items) {
                 : [0, 0]) || [],
         })) || [],
         url: singleRepo ? item.path : simplifyGitHubUrl(item.url),
+        repository: {
+            nameWithOwner: item.repository.nameWithOwner,
+            url: item.repository.url,
+        },
     }));
     const result = {
         items: optimizedItems,
@@ -1333,8 +1587,8 @@ function extractSingleRepository$1(items) {
     return allSameRepo ? firstRepo : null;
 }
 /**
- * Build command line arguments for GitHub CLI with improved parameter handling.
- * Preserves quoted phrases and supports both AND search and exact phrase matching.
+ * Build command line arguments for GitHub CLI following the exact CLI format.
+ * Uses proper flags (--flag=value) instead of qualifiers where appropriate.
  */
 function buildGitHubCliArgs(params) {
     const args = ['code'];
@@ -1344,39 +1598,52 @@ function buildGitHubCliArgs(params) {
     if (searchQuery) {
         args.push(searchQuery);
     }
-    // Add extracted qualifiers from the query
+    // Add extracted qualifiers from the query (these should remain as qualifiers)
     extractedQualifiers.forEach(qualifier => {
         args.push(qualifier);
     });
-    // Add explicit parameters as qualifiers
+    // Add explicit parameters as CLI flags (following GitHub CLI format)
     if (params.language && !params.query.includes('language:')) {
-        args.push(`language:${params.language}`);
+        args.push(`--language=${params.language}`);
+    }
+    // Handle owner and repo parameters properly
+    if (params.repo && !params.query.includes('repo:')) {
+        const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
+        repos.forEach(repo => {
+            // If both owner and repo are provided, combine them for --repo flag
+            if (params.owner && !repo.includes('/')) {
+                const owners = Array.isArray(params.owner)
+                    ? params.owner
+                    : [params.owner];
+                owners.forEach(owner => args.push(`--repo=${owner}/${repo}`));
+            }
+            else {
+                // Repo is already in owner/repo format or no owner provided
+                args.push(`--repo=${repo}`);
+            }
+        });
     }
-    if (params.owner &&
+    else if (params.owner &&
         !params.query.includes('org:') &&
         !params.query.includes('user:')) {
+        // Only owner provided, no repo - use --owner flag for organization-wide search
         const owners = Array.isArray(params.owner) ? params.owner : [params.owner];
-        owners.forEach(owner => args.push(`org:${owner}`));
-    }
-    if (params.repo && !params.query.includes('repo:')) {
-        const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
-        repos.forEach(repo => args.push(`repo:${repo}`));
+        owners.forEach(owner => args.push(`--owner=${owner}`));
     }
     if (params.filename && !params.query.includes('filename:')) {
-        args.push(`filename:${params.filename}`);
+        args.push(`--filename=${params.filename}`);
     }
     if (params.extension && !params.query.includes('extension:')) {
-        args.push(`extension:${params.extension}`);
+        args.push(`--extension=${params.extension}`);
     }
     if (params.size && !params.query.includes('size:')) {
-        args.push(`size:${params.size}`);
+        args.push(`--size=${params.size}`);
     }
-    // Handle match parameter
+    // Handle match parameter - use --match flag
     if (params.match) {
-        const matches = Array.isArray(params.match) ? params.match : [params.match];
-        args.push(`in:${matches.join(',')}`);
+        args.push(`--match=${params.match}`);
     }
-    // Add limit
+    // Add limit flag
     if (params.limit) {
         args.push(`--limit=${params.limit}`);
     }
@@ -1396,69 +1663,38 @@ async function searchGitHubCode(params) {
         }
         catch (error) {
             const errorMessage = error.message || '';
-            return handleSearchError(errorMessage); // Delegating error handling
+            return handleSearchError(errorMessage);
         }
     });
 }
 /**
- * Enhanced validation with helpful suggestions
+ * Parse search query to preserve quoted phrases and extract qualifiers.
+ * Handles:
+ * - Quoted phrases: "error handling" -> kept as single unit
+ * - Multiple terms: react lifecycle -> both terms for AND search
+ * - Mixed: "error handling" debug -> phrase + term
+ * - Qualifiers: language:javascript -> extracted separately
+ * - Quote escaping issues: automatically fixes common mistakes
  */
-function validateSearchParameters(params) {
-    // Query validation
-    if (!params.query.trim()) {
-        return ERROR_MESSAGES.EMPTY_QUERY;
-    }
-    if (params.query.length > 1000) {
-        return ERROR_MESSAGES.QUERY_TOO_LONG_1000;
+function parseSearchQuery(query) {
+    const qualifiers = [];
+    const searchTerms = [];
+    // Clean up common quote escaping issues
+    let cleanedQuery = query;
+    // Fix escaped quotes that shouldn't be escaped
+    if (cleanedQuery.includes('\\"') && !cleanedQuery.includes(' ')) {
+        cleanedQuery = cleanedQuery.replace(/\\"/g, '');
     }
-    // Repository validation - ensure owner is provided correctly
-    if (params.owner &&
-        typeof params.owner === 'string' &&
-        params.owner.includes('/')) {
-        return 'Owner parameter should contain only the username/org name, not owner/repo format. For repository-specific searches, use org: or user: qualifiers in the query.';
+    // Fix single-word queries wrapped in quotes unnecessarily
+    if (cleanedQuery.startsWith('"') &&
+        cleanedQuery.endsWith('"') &&
+        !cleanedQuery.slice(1, -1).includes(' ')) {
+        cleanedQuery = cleanedQuery.slice(1, -1);
     }
-    if (Array.isArray(params.owner)) {
-        const hasSlashFormat = params.owner.some(owner => owner.includes('/'));
-        if (hasSlashFormat) {
-            return 'Owner parameter should contain only usernames/org names, not owner/repo format. For repository-specific searches, use repo: qualifier in the query.';
-        }
-    }
-    // Add validation for file size limit
-    if (params.size) {
-        if (!/^([<>]\d+|\d+\.\.\d+)$/.test(params.size)) {
-            return ERROR_MESSAGES.INVALID_SIZE_FORMAT;
-        }
-    }
-    // Validate search scope
-    if (params.match) {
-        const validScopes = ['file', 'path'];
-        const scopes = Array.isArray(params.match) ? params.match : [params.match];
-        if (!scopes.every(scope => validScopes.includes(scope))) {
-            return ERROR_MESSAGES.INVALID_SEARCH_SCOPE;
-        }
-    }
-    // Note about repository limitations (This is a note, not a hard error)
-    // This return statement was returning null before, so it shouldn't be an issue
-    // if (params.repo || params.owner) {
-    //   return null; // Return warning about repository limitations
-    // }
-    return null; // No validation errors
-}
-/**
- * Parse search query to preserve quoted phrases and extract qualifiers.
- * Handles:
- * - Quoted phrases: "error handling" -> kept as single unit
- * - Multiple terms: react lifecycle -> both terms for AND search
- * - Mixed: "error handling" debug -> phrase + term
- * - Qualifiers: language:javascript -> extracted separately
- */
-function parseSearchQuery(query) {
-    const qualifiers = [];
-    const searchTerms = [];
     // Regular expression to match quoted strings or individual words/qualifiers
     const tokenRegex = /"([^"]+)"|([^\s]+)/g;
     let match;
-    while ((match = tokenRegex.exec(query)) !== null) {
+    while ((match = tokenRegex.exec(cleanedQuery)) !== null) {
         const token = match[1] || match[2]; // match[1] is quoted content, match[2] is unquoted
         // Check if it's a qualifier (contains : but not inside quotes)
         if (!match[1] && token.includes(':') && /^[a-zA-Z]+:/.test(token)) {
@@ -1482,10 +1718,10 @@ function parseSearchQuery(query) {
 }
 
 const GITHUB_SEARCH_COMMITS_TOOL_NAME = 'githubSearchCommits';
-const DESCRIPTION$5 = `Search commit history across GitHub repositories. Supports filtering by repository, author, date ranges, and commit attributes. Parameters: query (optional), owner (optional - GitHub username/org, NOT owner/repo), repo (optional - repository name, use with owner for specific repo), author (optional), authorName (optional), authorEmail (optional), committer (optional), committerName (optional), committerEmail (optional), authorDate (optional), committerDate (optional), hash (optional), parent (optional), tree (optional), merge (optional), visibility (optional), limit (optional), sort (optional), order (optional).`;
+const DESCRIPTION$6 = `Search commit history across GitHub repositories. Find commits by message, author, date, or repository. Supports advanced filtering for comprehensive commit analysis. Returns commit SHA, message, author, and date information.`;
 function registerGitHubSearchCommitsTool(server) {
     server.registerTool(GITHUB_SEARCH_COMMITS_TOOL_NAME, {
-        description: DESCRIPTION$5,
+        description: DESCRIPTION$6,
         inputSchema: {
             query: z
                 .string()
@@ -1495,11 +1731,11 @@ function registerGitHubSearchCommitsTool(server) {
             owner: z
                 .string()
                 .optional()
-                .describe('Repository owner/org name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). Use with repo parameter for repository-specific searches.'),
+                .describe('Repository owner/organization name only (e.g., "facebook", "microsoft"). Do NOT include repository name. Must be used with repo parameter for repository-specific searches.'),
             repo: z
                 .string()
                 .optional()
-                .describe('Repository name only (e.g., "vscode", "react", NOT "owner/repo"). Must be used together with owner parameter.'),
+                .describe('Repository name only (e.g., "react", "vscode"). Do NOT include owner prefix. Must be used together with owner parameter.'),
             // Author filters
             author: z
                 .string()
@@ -1749,10 +1985,10 @@ function buildGitHubCommitCliArgs(params) {
 }
 
 const GITHUB_SEARCH_ISSUES_TOOL_NAME = 'githubSearchIssues';
-const DESCRIPTION$4 = `Search GitHub issues for bug discovery and feature analysis. Supports filtering by state, labels, assignee, dates, and more. Parameters: query (required), owner (optional - GitHub username/org, NOT owner/repo), repo (optional - repository name, use with owner for specific repo), app (optional), archived (optional), assignee (optional), author (optional), closed (optional), commenter (optional), comments (optional), created (optional), includePrs (optional), interactions (optional), involves (optional), labels (optional), language (optional), locked (optional), match (optional), mentions (optional), milestone (optional), noAssignee (optional), noLabel (optional), noMilestone (optional), noProject (optional), project (optional), reactions (optional), state (optional), teamMentions (optional), updated (optional), visibility (optional), sort (optional), order (optional), limit (optional).`;
+const DESCRIPTION$5 = `Search GitHub issues for bug reports, feature requests, and discussions. Find issues by keywords, state, labels, author, or repository. Returns issue number, title, state, labels, and metadata for effective issue tracking and analysis.`;
 function registerSearchGitHubIssuesTool(server) {
     server.registerTool(GITHUB_SEARCH_ISSUES_TOOL_NAME, {
-        description: DESCRIPTION$4,
+        description: DESCRIPTION$5,
         inputSchema: {
             query: z
                 .string()
@@ -1762,11 +1998,11 @@ function registerSearchGitHubIssuesTool(server) {
                 .string()
                 .min(1)
                 .optional()
-                .describe('Repository owner/org name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). Use with repo parameter for repository-specific searches.'),
+                .describe('Repository owner/organization name only (e.g., "facebook", "microsoft"). Do NOT include repository name. Must be used with repo parameter for repository-specific searches.'),
             repo: z
                 .string()
                 .optional()
-                .describe('Repository name only (e.g., "vscode", "react", NOT "owner/repo"). Must be used together with owner parameter.'),
+                .describe('Repository name only (e.g., "react", "vscode"). Do NOT include owner prefix. Must be used together with owner parameter.'),
             app: z
                 .string()
                 .optional()
@@ -1820,7 +2056,7 @@ function registerSearchGitHubIssuesTool(server) {
             label: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Label names (bug, feature, etc.). Can be single string or array.'),
+                .describe('Label names. Can be single string or array.'),
             language: z.string().optional().describe('Repository language'),
             locked: z.boolean().optional().describe('Conversation locked status'),
             match: z
@@ -1961,6 +2197,51 @@ async function searchGitHubIssues(params) {
             comments: issue.comments,
             reactions: issue.reactions?.total_count || 0,
         }));
+        // Smart fallback suggestions for no results
+        if (cleanIssues.length === 0) {
+            const fallbackSuggestions = [];
+            // Analyze search parameters for specific suggestions
+            if (params.state === 'closed') {
+                fallbackSuggestions.push('• Try state:open or remove state filter');
+            }
+            if (params.author) {
+                fallbackSuggestions.push('• Remove author filter for broader search');
+                fallbackSuggestions.push(`• Use github_search_code to find ${params.author}'s contributions`);
+            }
+            if (params.label) {
+                const labels = Array.isArray(params.label)
+                    ? params.label
+                    : [params.label];
+                fallbackSuggestions.push(`• Try broader labels or remove label filter`);
+                fallbackSuggestions.push(`• Search for label variations: ${labels.map(l => `"${l}"`).join(', ')}`);
+            }
+            if (params.owner && params.repo) {
+                fallbackSuggestions.push('• Check repository name spelling');
+                fallbackSuggestions.push('• Use github_view_repo_structure to verify repository exists');
+            }
+            else if (params.owner) {
+                fallbackSuggestions.push('• Remove owner filter for global search');
+                fallbackSuggestions.push('• Use github_search_repos to find organization repositories');
+            }
+            if (params.created || params.updated) {
+                fallbackSuggestions.push('• Expand date range or remove date filters');
+            }
+            // Add general alternatives
+            fallbackSuggestions.push('• Try broader search terms');
+            fallbackSuggestions.push('• Use github_search_pull_requests for related development activity');
+            fallbackSuggestions.push('• Use github_search_code to find implementation patterns');
+            return createResult({
+                error: `No issues found for query: "${params.query}"
+
+Try these alternatives:
+${fallbackSuggestions.join('\n')}
+
+Discovery strategies:
+• Broader terms: "error" instead of "TypeError"
+• Remove filters: state, labels, author
+• Related searches: pull requests, code implementations`,
+            });
+        }
         const searchResult = {
             results: cleanIssues,
         };
@@ -2083,10 +2364,10 @@ function buildGitHubIssuesAPICommand(params) {
 
 // TODO: add PR commeents. e.g, gh pr view <PR_NUMBER_OR_URL_OR_BRANCH> --comments
 const GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME = 'githubSearchPullRequests';
-const DESCRIPTION$3 = `Search pull requests for implementation discovery and code review analysis. Supports filtering by state, review status, branches, and more. Parameters: query (required), owner (optional - GitHub username/org, NOT owner/repo), repo (optional - repository name, use with owner for specific repo), author (optional), assignee (optional), mentions (optional), commenter (optional), involves (optional), reviewedBy (optional), reviewRequested (optional), state (optional), head (optional), base (optional), language (optional), created (optional), updated (optional), mergedAt (optional), closed (optional), draft (optional), checks (optional), merged (optional), review (optional), limit (optional), sort (optional), order (optional).`;
+const DESCRIPTION$4 = `Search GitHub pull requests for code changes, feature implementations, and bug fixes. Find PRs by keywords, state, author, review status, or repository. Returns PR number, title, state, branches, and review information for code review analysis.`;
 function registerSearchGitHubPullRequestsTool(server) {
     server.registerTool(GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME, {
-        description: DESCRIPTION$3,
+        description: DESCRIPTION$4,
         inputSchema: {
             query: z
                 .string()
@@ -2095,11 +2376,11 @@ function registerSearchGitHubPullRequestsTool(server) {
             owner: z
                 .string()
                 .optional()
-                .describe('Repository owner/org name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). Use with repo parameter for repository-specific searches.'),
+                .describe('Repository owner/organization name only (e.g., "facebook", "microsoft"). Do NOT include repository name. Must be used with repo parameter for repository-specific searches.'),
             repo: z
                 .string()
                 .optional()
-                .describe('Repository name only (e.g., "vscode", "react", NOT "owner/repo"). Must be used together with owner parameter.'),
+                .describe('Repository name only (e.g., "react", "vscode"). Do NOT include owner prefix. Must be used together with owner parameter.'),
             author: z.string().optional().describe('GitHub username of PR author'),
             assignee: z.string().optional().describe('GitHub username of assignee'),
             mentions: z.string().optional().describe('PRs mentioning this user'),
@@ -2118,10 +2399,7 @@ function registerSearchGitHubPullRequestsTool(server) {
                 .optional()
                 .describe('PR state. Default: all'),
             head: z.string().optional().describe('Source branch name'),
-            base: z
-                .string()
-                .optional()
-                .describe('Target branch name (main, develop, etc.)'),
+            base: z.string().optional().describe('Target branch name'),
             language: z.string().optional().describe('Repository language'),
             created: z
                 .string()
@@ -2409,26 +2687,38 @@ function buildGitHubPullRequestsAPICommand(params) {
  * 4. Recent Quality:
  * { stars: ">1000", created: ">2023-01-01", limit: 10 }
  *
+ * RESEARCH & EXPLORATION PATTERNS:
+ *
+ * 1. Topic-based Discovery (HIGHLY RECOMMENDED for unknown projects):
+ * { topic: ["machine-learning", "nlp", "pytorch"], limit: 20 }
+ * { topic: ["kubernetes", "monitoring"], stars: ">100", limit: 15 }
+ *
+ * 2. Exploratory Research Flow:
+ * - Start with topics to discover repositories
+ * - Then use githubViewRepoStructure to understand project layout
+ * - Read README.md, docs/, and configuration files
+ * - Finally use githubSearchCode for specific implementations
+ *
  * AVOID: OR queries + language filter, 5+ filters, multi-word OR
  * TIP: Use limit parameter instead of adding more filters
  */
 const GITHUB_SEARCH_REPOSITORIES_TOOL_NAME = 'githubSearchRepositories';
-const DESCRIPTION$2 = `Search GitHub repositories using GitHub's repository search API with comprehensive filtering.
-
-Search Logic (AND operation for multiple terms):
-- Multiple words: "react typescript" → repositories containing BOTH "react" AND "typescript"
-- Exact phrases: "web framework" → repositories with exact phrase "web framework"
-- Mixed: "machine learning" python → exact phrase "machine learning" AND word "python"
-- Filter combinations: language:javascript stars:>1000 → JavaScript repos with 1000+ stars
-
-Supported Filters: language, stars (ranges), topics, owner/org, license, dates (created/updated), 
-size, forks, community metrics (good-first-issues, help-wanted), archived status, visibility.
-
-Examples:
-- Popular projects: stars:">1000" language:typescript
-- Beginner-friendly: good-first-issues:">5" stars:"100..5000"
-- Recent quality: created:">2023-01-01" stars:">500"
-- Organization repos: owner:microsoft language:python`;
+const DESCRIPTION$3 = `Search GitHub repositories for project discovery and ecosystem analysis. TOPICS are the most powerful discovery feature.
+
+TOPIC-DRIVEN DISCOVERY:
+- Topics reveal ecosystem relationships and quality indicators  
+- Combine topics for targeted discovery: ["framework", "use-case", "language"]
+- Topics beat keyword searches for unknown project exploration
+
+PROGRESSIVE SEARCH STRATEGY:
+- Start with topic combinations for broad discovery
+- Add quality filters (stars, activity) for refinement
+- Use multiple separate searches vs complex single queries
+
+RESEARCH INTEGRATION:
+- Repository discovery → structure analysis → implementation patterns
+- Quality assessment via community metrics and activity
+- Bridge to code search and file analysis tools`;
 /**
  * Extract owner/repo information from various query formats
  */
@@ -2461,21 +2751,21 @@ function extractOwnerRepoFromQuery(query) {
 }
 function registerSearchGitHubReposTool(server) {
     server.registerTool(GITHUB_SEARCH_REPOSITORIES_TOOL_NAME, {
-        description: DESCRIPTION$2,
+        description: DESCRIPTION$3,
         inputSchema: {
             query: z
                 .string()
                 .optional()
-                .describe('Search query with AND logic between terms. Multiple words require ALL to be present. Use quotes for exact phrases. Examples: react typescript (both words), "web framework" (exact phrase), "machine learning" python (phrase + word).'),
+                .describe('Search query with AND logic between terms. Multiple words require ALL to be present. Use quotes for exact phrases.'),
             // CORE FILTERS (GitHub CLI flags)
             owner: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Repository owner or organization name(s). Format: "microsoft" or ["facebook", "google"]. Do NOT use owner/repo format. Dramatically narrows search scope to specific organizations.'),
+                .describe('Repository owner/organization name(s) (e.g., "facebook", ["google", "microsoft"]). Search within specific organizations. Do NOT use owner/repo format - just the organization/username.'),
             language: z
                 .string()
                 .optional()
-                .describe('Programming language filter (javascript, python, typescript, go, etc). Filters repositories by primary language. Essential for language-specific searches.'),
+                .describe('Programming language filter. Filters repositories by primary language. Essential for language-specific searches.'),
             stars: z
                 .union([
                 z.number().int().min(0),
@@ -2484,11 +2774,11 @@ function registerSearchGitHubReposTool(server) {
                     .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">1000", ">=500", "<100", "<=50", "10..100", or exact number "50"'),
             ])
                 .optional()
-                .describe('Star count filter. Format: ">1000" (more than), ">=500" (more than or equal), "<100" (less than), "<=50" (less than or equal), "100..1000" (range), "500" (exact). Examples from docs: ">1000", "100..5000", "<100"'),
+                .describe('Star count filter. Format: ">1000" (more than), ">=500" (more than or equal), "<100" (less than), "<=50" (less than or equal), "100..1000" (range), "500" (exact).'),
             topic: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Repository topics filter. Examples: "machine-learning", ["react", "typescript"]. Topics use kebab-case format (machine-learning, web-development).'),
+                .describe('Repository topics filter. Excellent for discovering projects and understanding repository ecosystems. Topics use kebab-case format.'),
             forks: z
                 .union([
                 z.number().int().min(0),
@@ -2497,7 +2787,7 @@ function registerSearchGitHubReposTool(server) {
                     .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">100", ">=50", "<10", "<=5", "10..100", or exact number "5"'),
             ])
                 .optional()
-                .describe('Fork count filter. Format: ">100" (more than), ">=50" (more than or equal), "<10" (less than), "<=5" (less than or equal), "10..100" (range), "5" (exact). Examples from docs: ">100", "10..100", "<10"'),
+                .describe('Fork count filter. Format: ">100" (more than), ">=50" (more than or equal), "<10" (less than), "<=5" (less than or equal), "10..100" (range), "5" (exact).'),
             // Match CLI parameter name exactly
             'number-topics': z
                 .union([
@@ -2507,40 +2797,40 @@ function registerSearchGitHubReposTool(server) {
                     .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">5", ">=3", "<10", "<=2", "3..10", or exact number "5"'),
             ])
                 .optional()
-                .describe('Number of topics filter. Format: ">5" (many topics), ">=3" (at least 3), "<10" (few topics), "1..3" (range), "5" (exact). Well-documented projects typically have 3-10 topics.'),
+                .describe('Number of topics filter. Format: ">5" (many topics), ">=3" (at least 3), "<10" (few topics), "1..3" (range), "5" (exact).'),
             // QUALITY & STATE FILTERS
             license: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('License filter. Examples: "mit", "apache-2.0", ["mit", "apache-2.0"]. Common licenses: mit, apache-2.0, gpl-3.0, bsd-3-clause.'),
+                .describe('License filter.'),
             archived: z
                 .boolean()
                 .optional()
-                .describe('Archive status filter. false (active repos only), true (archived repos only). Use false to find actively maintained projects.'),
+                .describe('Archive status filter. false (active repos only), true (archived repos only).'),
             'include-forks': z
                 .enum(['false', 'true', 'only'])
                 .optional()
-                .describe('Fork inclusion. "false" (exclude forks), "true" (include forks), "only" (forks only). Use "false" for original projects.'),
+                .describe('Fork inclusion. "false" (exclude forks), "true" (include forks), "only" (forks only).'),
             visibility: z
                 .enum(['public', 'private', 'internal'])
                 .optional()
-                .describe('Repository visibility. "public" (open source), "private" (private repos you have access to), "internal" (organization internal).'),
+                .describe('Repository visibility.'),
             // DATE & SIZE FILTERS
             created: z
                 .string()
                 .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2020-01-01", ">=2020-01-01", "<2023-12-31", "<=2023-12-31", "2020-01-01..2023-12-31", or exact date "2023-01-01"')
                 .optional()
-                .describe('Repository creation date filter. Format: ">2020-01-01" (after), ">=2020-01-01" (on or after), "<2023-12-31" (before), "<=2023-12-31" (on or before), "2020-01-01..2023-12-31" (range), "2023-01-01" (exact). Examples from docs: ">2020-01-01", "2023-01-01..2023-12-31"'),
+                .describe('Repository creation date filter. Format: ">2020-01-01" (after), ">=2020-01-01" (on or after), "<2023-12-31" (before), "<=2023-12-31" (on or before), "2020-01-01..2023-12-31" (range), "2023-01-01" (exact).'),
             updated: z
                 .string()
                 .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2024-01-01", ">=2024-01-01", "<2022-01-01", "<=2022-01-01", "2023-01-01..2024-12-31", or exact date "2024-01-01"')
                 .optional()
-                .describe('Last updated date filter. Format: ">2024-01-01" (recently updated), ">=2024-01-01" (on or after), "<2022-01-01" (not recently updated), "2023-01-01..2024-12-31" (range). Essential for finding actively maintained projects. Examples from docs: ">2024-01-01", "2022-01-01..2023-12-31"'),
+                .describe('Last updated date filter. Format: ">2024-01-01" (recently updated), ">=2024-01-01" (on or after), "<2022-01-01" (not recently updated), "2023-01-01..2024-12-31" (range).'),
             size: z
                 .string()
                 .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid size format. Use: ">1000", ">=500", "<100", "<=50", "100..1000", or exact number "500"')
                 .optional()
-                .describe('Repository size filter in KB. Format: ">1000" (large projects), ">=500" (medium-large), "<100" (small projects), "<=50" (tiny), "100..1000" (medium range), "500" (exact). Examples from docs: ">1000", "100..1000", "<100"'),
+                .describe('Repository size filter in KB. Format: ">1000" (large projects), ">=500" (medium-large), "<100" (small projects), "<=50" (tiny), "100..1000" (medium range), "500" (exact).'),
             // COMMUNITY FILTERS - Match CLI parameter names exactly
             'good-first-issues': z
                 .union([
@@ -2550,7 +2840,7 @@ function registerSearchGitHubReposTool(server) {
                     .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: number, ">5", ">=10", "<20", "<=15", or "5..20"'),
             ])
                 .optional()
-                .describe('Good first issues count. Format: ">5" (many beginner issues), "1..10" (some beginner issues). Perfect for finding beginner-friendly open source projects.'),
+                .describe('Good first issues count. Format: ">5" (many beginner issues), "1..10" (some beginner issues).'),
             'help-wanted-issues': z
                 .union([
                 z.number().int().min(0),
@@ -2559,7 +2849,7 @@ function registerSearchGitHubReposTool(server) {
                     .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: number, ">5", ">=10", "<20", "<=15", or "5..20"'),
             ])
                 .optional()
-                .describe('Help wanted issues count. Format: ">10" (many help wanted), "1..5" (some help wanted). Great for finding projects actively seeking contributors.'),
+                .describe('Help wanted issues count. Format: ">10" (many help wanted), "1..5" (some help wanted).'),
             followers: z
                 .union([
                 z.number().int().min(0),
@@ -2568,12 +2858,15 @@ function registerSearchGitHubReposTool(server) {
                     .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">1000", ">=500", "<100", "<=50", "100..1000", or exact number "500"'),
             ])
                 .optional()
-                .describe('Repository owner followers count. Format: ">1000" (popular developers), ">=500" (established developers), "<100" (smaller developers), "100..1000" (range). Indicates developer/org reputation.'),
-            // SEARCH SCOPE
+                .describe('Repository owner followers count. Format: ">1000" (popular developers), ">=500" (established developers), "<100" (smaller developers), "100..1000" (range).'),
+            // SEARCH SCOPE - Match CLI exactly
             match: z
-                .enum(['name', 'description', 'readme'])
+                .union([
+                z.enum(['name', 'description', 'readme']),
+                z.array(z.enum(['name', 'description', 'readme'])),
+            ])
                 .optional()
-                .describe('Search scope. "name" (repository names only), "description" (descriptions only), "readme" (README content). Default searches all fields.'),
+                .describe('Search scope. "name" (repository names only), "description" (descriptions only), "readme" (README content). Can be single value or array.'),
             // SORTING & LIMITS - Match CLI defaults exactly
             sort: z
                 .enum([
@@ -2585,12 +2878,12 @@ function registerSearchGitHubReposTool(server) {
             ])
                 .optional()
                 .default('best-match')
-                .describe('Sort criteria. "stars" (popularity), "updated" (recent activity), "forks" (community engagement), "help-wanted-issues" (contribution opportunities), "best-match" (relevance).'),
+                .describe('Sort criteria.'),
             order: z
                 .enum(['asc', 'desc'])
                 .optional()
                 .default('desc')
-                .describe('Sort order direction. "desc" (descending, highest first), "asc" (ascending, lowest first). Default is descending for most useful results.'),
+                .describe('Sort order direction.'),
             limit: z
                 .number()
                 .int()
@@ -2598,7 +2891,7 @@ function registerSearchGitHubReposTool(server) {
                 .max(100)
                 .optional()
                 .default(30)
-                .describe('Maximum number of repositories to return (1-100). Default: 30. Higher values may increase response time.'),
+                .describe('Maximum number of repositories to return (1-100).'),
         },
         annotations: {
             title: 'GitHub Repository Search',
@@ -2637,34 +2930,87 @@ function registerSearchGitHubReposTool(server) {
                 enhancedArgs.forks;
             if (!hasPrimaryFilter) {
                 return createResult({
-                    error: SUGGESTIONS.REPO_SEARCH_PRIMARY_FILTER,
+                    error: `Repository search requires at least one filter. Try these patterns:
+• Topic discovery: { topic: ["react", "typescript"] }
+• Quality search: { stars: ">1000", language: "javascript" }
+• Organization: { owner: "microsoft", language: "python" }
+• Recent projects: { created: ">2023-01-01", stars: ">100" }`,
                 });
             }
             // First attempt: Search with current parameters
             const result = await searchGitHubRepos(enhancedArgs);
+            if (result.isError) {
+                const errorMsg = result.content?.[0]?.text || '';
+                // Smart fallbacks based on error type
+                if (errorMsg.includes('rate limit')) {
+                    return createResult({
+                        error: `GitHub API rate limit. Smart alternatives:
+• Try npm package search for package discovery
+• Use broader filters (remove stars/forks constraints)
+• Search fewer organizations at once
+• Wait 5-10 minutes and retry`,
+                    });
+                }
+                if (errorMsg.includes('authentication')) {
+                    return createResult({
+                        error: `Authentication required. Quick fix:
+1. Run: gh auth login
+2. For private repos: use api_status_check to verify access
+3. Public repos should work without auth - check query`,
+                    });
+                }
+                return result; // Return original error for other cases
+            }
+            // Check if we got results
+            const resultData = JSON.parse(result.content[0].text);
+            const hasResults = resultData.total_count > 0;
+            // Smart fallback strategies for no results
+            if (!hasResults) {
+                const fallbackSuggestions = [];
+                if (enhancedArgs.query) {
+                    fallbackSuggestions.push('• Try broader search terms or remove query filter');
+                }
+                if (enhancedArgs.language) {
+                    fallbackSuggestions.push('• Remove language filter for broader discovery');
+                }
+                if (enhancedArgs.stars || enhancedArgs.forks) {
+                    fallbackSuggestions.push('• Lower quality thresholds (stars/forks)');
+                }
+                if (!enhancedArgs.topic) {
+                    fallbackSuggestions.push('• Try topic-based search: { topic: ["web", "api"] }');
+                }
+                if (enhancedArgs.owner) {
+                    fallbackSuggestions.push('• Search without owner filter for global discovery');
+                    fallbackSuggestions.push('• Use npm package search if looking for packages');
+                }
+                return createResult({
+                    error: `No repositories found. Try these alternatives:
+${fallbackSuggestions.join('\n')}
+
+Discovery patterns:
+• Topic exploration: { topic: ["react"] }
+• Quality discovery: { stars: ">100", language: "python" }
+• Recent activity: { updated: ">2024-01-01" }`,
+                });
+            }
             // Fallback for private repositories: If no results and owner is specified, try with private visibility
-            if (!result.isError) {
-                const resultData = JSON.parse(result.content[0].text);
-                if (resultData.total === 0 &&
-                    enhancedArgs.owner &&
-                    !enhancedArgs.visibility) {
-                    // Try searching with private visibility for organization repos
-                    const privateSearchArgs = {
-                        ...enhancedArgs,
-                        visibility: 'private',
-                    };
-                    const privateResult = await searchGitHubRepos(privateSearchArgs);
-                    if (!privateResult.isError) {
-                        const privateData = JSON.parse(privateResult.content[0].text);
-                        if (privateData.total > 0) {
-                            // Return private results with note
-                            return createResult({
-                                data: {
-                                    ...privateData,
-                                    note: 'Found results in private repositories within the specified organization.',
-                                },
-                            });
-                        }
+            if (enhancedArgs.owner && !enhancedArgs.visibility) {
+                // Try searching with private visibility for organization repos
+                const privateSearchArgs = {
+                    ...enhancedArgs,
+                    visibility: 'private',
+                };
+                const privateResult = await searchGitHubRepos(privateSearchArgs);
+                if (!privateResult.isError) {
+                    const privateData = JSON.parse(privateResult.content[0].text);
+                    if (privateData.total_count > 0) {
+                        // Return private results with note
+                        return createResult({
+                            data: {
+                                ...privateData,
+                                note: 'Found results in private repositories within the specified organization.',
+                            },
+                        });
                     }
                 }
             }
@@ -2819,17 +3165,300 @@ function buildGitHubReposSearchCommand(params) {
     // SEARCH SCOPE
     addArg('match', 'match');
     // SORTING AND LIMITS
-    addArg('limit', 'limit');
-    addArg('order', 'order');
     const sortBy = params.sort || 'best-match';
     if (sortBy !== 'best-match') {
         args.push(`--sort=${sortBy}`);
     }
+    addArg('order', 'order');
+    // Always add limit with default of 30
+    const limit = params.limit || 30;
+    args.push(`--limit=${limit}`);
     return { command: 'search', args };
 }
 
+const GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME = 'githubViewRepoStructure';
+const DESCRIPTION$2 = `Explore GitHub repository structure and validate repository access. ESSENTIAL for understanding project organization.
+
+REPOSITORY VALIDATION:
+- Verify repository existence and accessibility
+- Navigate from root to understand project layout  
+- Identify key directories and file patterns
+
+PROJECT UNDERSTANDING:
+- Discover configuration files, documentation, source structure
+- Validate paths before accessing specific files
+- Understand architecture and organization patterns
+
+WORKFLOW INTEGRATION:
+- First step after repository discovery
+- Guides subsequent file access and code search
+- Prevents "file not found" errors through validation
+- Essential for comprehensive repository analysis`;
+function registerViewRepositoryStructureTool(server) {
+    server.registerTool(GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME, {
+        description: DESCRIPTION$2,
+        inputSchema: {
+            owner: z
+                .string()
+                .min(1)
+                .max(100)
+                .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/, 'Invalid GitHub username/org format')
+                .describe('Repository owner/organization name (e.g., "facebook", "microsoft"). Do NOT include repository name.'),
+            repo: z
+                .string()
+                .min(1)
+                .max(100)
+                .regex(/^[a-zA-Z0-9._-]+$/, 'Invalid repository name format')
+                .describe(`Repository name under a organization. `),
+            branch: z
+                .string()
+                .min(1)
+                .max(255)
+                .regex(/^[^\s]+$/, 'Branch name cannot contain spaces')
+                .describe('Branch name (e.g., "main", "master", "develop"). Tool will automatically try default branch if specified branch is not found.'),
+            path: z
+                .string()
+                .optional()
+                .default('')
+                .refine(path => !path.includes('..'), 'Path traversal not allowed')
+                .refine(path => path.length <= 500, 'Path too long')
+                .describe('Directory path within repository (e.g., "src", "docs", "src/components"). Leave empty for root directory. Do NOT start with slash.'),
+        },
+        annotations: {
+            title: 'GitHub Repository Explorer',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        try {
+            const result = await viewRepositoryStructure(args);
+            return result;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            return createResult({
+                error: `Failed to explore repository. ${errorMessage}. Verify repository exists and is accessible`,
+            });
+        }
+    });
+}
+/**
+ * Views the structure of a GitHub repository at a specific path.
+ * Optimized for code analysis workflows with smart defaults and clear errors.
+ */
+async function viewRepositoryStructure(params) {
+    const cacheKey = generateCacheKey('gh-repo-structure', params);
+    return withCache(cacheKey, async () => {
+        const { owner, repo, branch, path = '' } = params;
+        try {
+            // Clean up path
+            const cleanPath = path.startsWith('/') ? path.substring(1) : path;
+            // Try the requested branch first, then fallback to main/master
+            const branchesToTry = await getSmartBranchFallback(owner, repo, branch);
+            let items = [];
+            let usedBranch = branch;
+            let lastError = null;
+            let attemptCount = 0;
+            const maxAttempts = branchesToTry.length;
+            const triedBranches = [];
+            for (const tryBranch of branchesToTry) {
+                if (attemptCount >= maxAttempts)
+                    break;
+                attemptCount++;
+                triedBranches.push(tryBranch);
+                try {
+                    const apiPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${tryBranch}`;
+                    const result = await executeGitHubCommand('api', [apiPath], {
+                        cache: false,
+                    });
+                    if (!result.isError) {
+                        const execResult = JSON.parse(result.content[0].text);
+                        const apiItems = execResult.result;
+                        items = Array.isArray(apiItems) ? apiItems : [apiItems];
+                        usedBranch = tryBranch;
+                        break;
+                    }
+                    else {
+                        lastError = new Error(result.content[0].text);
+                    }
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                    continue;
+                }
+            }
+            if (items.length === 0) {
+                // Check repository existence only after content fetch fails
+                const repoCheckResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
+                    cache: false,
+                });
+                if (repoCheckResult.isError) {
+                    const repoErrorMsg = repoCheckResult.content[0].text;
+                    if (repoErrorMsg.includes('404')) {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" not found. It might have been deleted, renamed, or made private. Use github_search_code to find current location.`,
+                        });
+                    }
+                    else if (repoErrorMsg.includes('403')) {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" exists but access is denied. Repository might be private or archived. Use api_status_check to verify permissions.`,
+                        });
+                    }
+                }
+                const errorMsg = lastError?.message || 'Unknown error';
+                if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
+                    if (path) {
+                        const searchSuggestion = await suggestPathSearchFallback(owner, path);
+                        return createResult({
+                            error: `Path "${path}" not found in any branch (tried: ${triedBranches.join(', ')}).${searchSuggestion}`,
+                        });
+                    }
+                    else {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" structure not accessible. Repository might be empty, private, or you might not have sufficient permissions. Use github_search_code with owner="${owner}" to find accessible repositories.`,
+                        });
+                    }
+                }
+                else if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
+                    return createResult({
+                        error: `Access denied to "${owner}/${repo}". Repository exists but might be private/archived. Use api_status_check to verify permissions, or github_search_code with owner="${owner}" to find accessible repositories.`,
+                    });
+                }
+                else {
+                    const searchSuggestion = path
+                        ? await suggestPathSearchFallback(owner, path)
+                        : '';
+                    return createResult({
+                        error: `Failed to access "${owner}/${repo}": ${errorMsg}. Check network connection and repository permissions.${searchSuggestion}`,
+                    });
+                }
+            }
+            // Limit total items to 100 for efficiency
+            const limitedItems = items.slice(0, 100);
+            // Sort: directories first, then alphabetically
+            limitedItems.sort((a, b) => {
+                if (a.type !== b.type) {
+                    return a.type === 'dir' ? -1 : 1;
+                }
+                return a.name.localeCompare(b.name);
+            });
+            // Create simplified, token-efficient structure
+            const files = limitedItems
+                .filter(item => item.type === 'file')
+                .map(item => ({
+                name: item.name,
+                size: item.size,
+                url: item.path, // Use path for fetching
+            }));
+            const folders = limitedItems
+                .filter(item => item.type === 'dir')
+                .map(item => ({
+                name: item.name,
+                url: item.path, // Use path for browsing
+            }));
+            return createResult({
+                data: {
+                    repository: `${owner}/${repo}`,
+                    branch: usedBranch,
+                    path: cleanPath || '/',
+                    githubBasePath: `https://api.github.com/repos/${owner}/${repo}/contents/`,
+                    files: {
+                        count: files.length,
+                        files: files,
+                    },
+                    folders: {
+                        count: folders.length,
+                        folders: folders,
+                    },
+                },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return createResult({
+                error: `Failed to access repository "${owner}/${repo}": ${errorMessage}. Verify repository name, permissions, and network connection.`,
+            });
+        }
+    });
+}
+/**
+ * Smart branch detection with automatic fallback to common branch names.
+ * Now includes more comprehensive branch detection and better error handling.
+ */
+async function getSmartBranchFallback(owner, repo, requestedBranch) {
+    const branches = new Set([requestedBranch]);
+    try {
+        // Try to get repository info to find default branch
+        const repoInfoResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
+            cache: false,
+        });
+        if (!repoInfoResult.isError) {
+            const execResult = JSON.parse(repoInfoResult.content[0].text);
+            const repoData = execResult.result;
+            const defaultBranch = repoData.default_branch;
+            if (defaultBranch) {
+                branches.add(defaultBranch);
+            }
+        }
+    }
+    catch {
+        // If we can't get repo info, proceed with standard fallbacks
+    }
+    // Add only main/master as fallback branches
+    const commonBranches = ['main', 'master'];
+    commonBranches.forEach(branch => branches.add(branch));
+    // Convert Set back to array, with requested branch first
+    const branchesArray = Array.from(branches);
+    branchesArray.sort((a, b) => {
+        if (a === requestedBranch)
+            return -1;
+        if (b === requestedBranch)
+            return 1;
+        return 0;
+    });
+    return branchesArray;
+}
+// Helper function to suggest path search strategy
+async function suggestPathSearchFallback(owner, path) {
+    try {
+        // Extract last path segment and try to find in same organization
+        const pathSegment = path.split('/').pop() || path;
+        const searchResult = await executeGitHubCommand('api', [
+            `/search/code?q=${encodeURIComponent(pathSegment)}+in:path+org:${owner}`,
+        ], { cache: false });
+        if (!searchResult.isError) {
+            const results = JSON.parse(searchResult.content[0].text);
+            if (results.total_count > 0) {
+                const firstMatch = results.items[0];
+                return ` Directory might be in ${firstMatch.repository.full_name}. Try these searches:\n1. github_search_code with query="${pathSegment}" owner="${owner}"\n2. github_search_code with query="path:${path}" owner="${owner}"`;
+            }
+        }
+    }
+    catch {
+        // Fallback to generic message if search fails
+    }
+    return ` Try these searches:\n1. github_search_code with query="${path.split('/').pop()}" owner="${owner}"\n2. github_search_code with query="path:${path}"`;
+}
+
 const NPM_PACKAGE_SEARCH_TOOL_NAME = 'npmPackageSearch';
-const DESCRIPTION$1 = `Search NPM packages with fuzzy matching. Supports multiple search terms and aggregates results. Use functional keywords like "react hooks", "auth", or "testing". Parameters: queries (required, string or array), searchLimit (optional).`;
+const DESCRIPTION$1 = `Search NPM packages by functionality keywords. PRIMARY ENTRY POINT for package-related queries.
+
+PACKAGE-FIRST STRATEGY:
+- Start here when users mention: libraries, dependencies, installations, alternatives
+- Use broad functional terms for discovery (not exact package names)
+- Bridge to GitHub tools via repository URLs from results
+
+SEARCH APPROACH:
+- Single functional terms work best for discovery
+- Multiple searches for different aspects/use-cases
+- Reveals ecosystem alternatives and quality indicators
+
+INTEGRATION WORKFLOW:
+- Package Discovery → Repository Analysis → Implementation Patterns
+- npmPackageSearch → npmViewPackage → GitHub repository tools
+- Compare alternatives by searching different functional terms`;
 const MAX_DESCRIPTION_LENGTH = 100;
 const MAX_KEYWORDS = 10;
 function registerNpmSearchTool(server) {
@@ -2838,7 +3467,7 @@ function registerNpmSearchTool(server) {
         inputSchema: {
             queries: z
                 .union([z.string(), z.array(z.string())])
-                .describe('Search terms for packages. Use functionality keywords: "react hooks", "cli tool", "testing"'),
+                .describe('Search terms for NPM packages (e.g., "react hooks", ["typescript", "eslint"], "data visualization"). Use functionality keywords rather than exact package names for best results.'),
             searchLimit: z
                 .number()
                 .int()
@@ -2864,28 +3493,136 @@ function registerNpmSearchTool(server) {
             const allPackages = [];
             // Search for each query term
             for (const query of queries) {
-                const result = await executeNpmCommand('search', [query, `--searchlimit=${searchLimit}`, '--json'], { cache: true });
-                if (!result.isError && result.content?.[0]?.text) {
-                    const packages = parseNpmSearchOutput(result.content[0].text);
-                    allPackages.push(...packages);
+                try {
+                    const result = await executeNpmCommand('search', [query, `--searchlimit=${searchLimit}`, '--json'], { cache: true });
+                    if (!result.isError && result.content?.[0]?.text) {
+                        const packages = parseNpmSearchOutput(result.content[0].text);
+                        allPackages.push(...packages);
+                    }
+                    else if (result.isError) {
+                        // Individual query failures are handled silently, continue with others
+                    }
+                }
+                catch (queryError) {
+                    // Continue with other queries even if one fails
                 }
             }
             const deduplicatedPackages = deduplicatePackages(allPackages);
             if (deduplicatedPackages.length > 0) {
+                const { nextSteps } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, { hasResults: true });
+                const hints = [];
+                if (nextSteps.length > 0) {
+                    hints.push('Next steps:');
+                    nextSteps.forEach(({ tool, reason }) => {
+                        hints.push(`• Use ${tool} ${reason}`);
+                    });
+                }
                 return createResult({
                     data: {
                         total_count: deduplicatedPackages.length,
                         results: deduplicatedPackages,
+                        hints: hints.length > 0 ? hints : undefined,
                     },
                 });
             }
+            // Smart fallback suggestions based on query patterns
+            const hasSpecificTerms = queries.some(q => q.includes('-') || q.includes('@') || q.length > 15);
+            const hasFrameworkTerms = queries.some(q => ['react', 'vue', 'angular', 'express', 'fastify'].some(fw => q.toLowerCase().includes(fw)));
+            let fallbackSuggestions = [
+                '• Try broader functional terms: "testing" instead of "jest-unit-test"',
+                '• Remove version numbers or specific constraints',
+                '• Use single keywords: "http" instead of "http-client-library"',
+            ];
+            if (hasSpecificTerms) {
+                fallbackSuggestions = [
+                    '• Use simpler terms: "validation" instead of "schema-validation-library"',
+                    '• Try category terms: "database", "testing", "auth"',
+                    ...fallbackSuggestions.slice(1),
+                ];
+            }
+            if (hasFrameworkTerms) {
+                fallbackSuggestions.unshift('• Try specific framework searches: "react hooks", "vue components"');
+            }
+            // Add GitHub integration suggestions
+            fallbackSuggestions.push('• Use github_search_repos with topic filters for project discovery');
+            fallbackSuggestions.push('• Check npm registry status: https://status.npmjs.org');
+            const { fallback } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, {
+                errorType: 'no_results',
+            });
+            const toolSuggestions = createToolSuggestion(TOOL_NAMES.NPM_PACKAGE_SEARCH, fallback);
             return createResult({
-                error: createNoResultsError('packages'),
+                error: getErrorWithSuggestion({
+                    baseError: createNpmPackageNotFoundError(queries.join(', ')),
+                    suggestion: [fallbackSuggestions.join('\n'), toolSuggestions],
+                }),
             });
         }
         catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            // Network/connectivity issues
+            if (errorMsg.includes('network') ||
+                errorMsg.includes('timeout') ||
+                errorMsg.includes('ENOTFOUND')) {
+                const { fallback } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, { });
+                return createResult({
+                    error: getErrorWithSuggestion({
+                        baseError: ERROR_MESSAGES.NPM_CONNECTION_FAILED,
+                        suggestion: [
+                            '• Check internet connection and npm registry status',
+                            '• Try fewer search terms to reduce load',
+                            '• Retry in a few moments',
+                            createToolSuggestion(TOOL_NAMES.NPM_PACKAGE_SEARCH, fallback),
+                        ],
+                    }),
+                });
+            }
+            // NPM CLI issues
+            if (errorMsg.includes('command not found') ||
+                errorMsg.includes('npm')) {
+                const { fallback } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, { });
+                return createResult({
+                    error: getErrorWithSuggestion({
+                        baseError: ERROR_MESSAGES.NPM_CLI_ERROR,
+                        suggestion: [
+                            '• Verify NPM installation: npm --version',
+                            '• Update NPM: npm install -g npm@latest',
+                            '• Check PATH environment variable',
+                            createToolSuggestion(TOOL_NAMES.NPM_PACKAGE_SEARCH, fallback),
+                        ],
+                    }),
+                });
+            }
+            // Permission/auth issues
+            if (errorMsg.includes('permission') ||
+                errorMsg.includes('403') ||
+                errorMsg.includes('401')) {
+                const { fallback } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, { errorType: 'access_denied' });
+                return createResult({
+                    error: getErrorWithSuggestion({
+                        baseError: ERROR_MESSAGES.NPM_PERMISSION_ERROR,
+                        suggestion: [
+                            '• Check npm login status: npm whoami',
+                            '• Use public registry search without auth',
+                            '• Verify npm registry configuration',
+                            createToolSuggestion(TOOL_NAMES.NPM_PACKAGE_SEARCH, fallback),
+                        ],
+                    }),
+                });
+            }
+            const { fallback } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, {
+                });
             return createResult({
-                error: createSearchFailedError('packages'),
+                error: getErrorWithSuggestion({
+                    baseError: ERROR_MESSAGES.PACKAGE_SEARCH_FAILED,
+                    suggestion: [
+                        `Error details: ${errorMsg}`,
+                        '',
+                        'Fallback strategies:',
+                        '• Check npm status and retry',
+                        '• Use broader search terms',
+                        createToolSuggestion(TOOL_NAMES.NPM_PACKAGE_SEARCH, fallback),
+                    ],
+                }),
             });
         }
     });
@@ -2937,7 +3674,25 @@ function parseNpmSearchOutput(output) {
 }
 
 const NPM_VIEW_PACKAGE_TOOL_NAME = 'npmViewPackage';
-const DESCRIPTION = `View detailed NPM package information including repository URL, exports, version history, dependencies, and download stats. Returns optimized metadata for code navigation. Parameters: packageName (required).`;
+const DESCRIPTION = `Analyze NPM packages for repository discovery and dependency insights. BRIDGE to GitHub ecosystem.
+
+PACKAGE ANALYSIS CAPABILITIES:
+- Repository URL discovery for GitHub exploration
+- Version history and release patterns
+- Export analysis for implementation understanding
+- Dependency metadata for ecosystem mapping
+
+GITHUB INTEGRATION:
+- Provides repository links for GitHub repository tools
+- Connects package metadata to source code analysis
+- Enables package-to-implementation research workflows
+- Essential for dependency and alternative evaluation
+
+USE CASES:
+- Repository discovery from package names
+- Version analysis and security assessment
+- Export structure for integration planning
+- Dependency research and ecosystem exploration`;
 function registerNpmViewPackageTool(server) {
     server.registerTool(NPM_VIEW_PACKAGE_TOOL_NAME, {
         description: DESCRIPTION,
@@ -2945,7 +3700,7 @@ function registerNpmViewPackageTool(server) {
             packageName: z
                 .string()
                 .min(1)
-                .describe('NPM package name (e.g., "react", "express", "@types/node")'),
+                .describe('NPM package name (e.g., "react", "express", "@types/node"). Include @ prefix for scoped packages.'),
         },
         annotations: {
             title: 'NPM Package Analyzer',
@@ -2968,18 +3723,87 @@ function registerNpmViewPackageTool(server) {
         }
         catch (error) {
             const errorMessage = error.message || '';
-            if (errorMessage.includes('not found')) {
+            // Package not found with smart discovery
+            if (errorMessage.includes('not found') ||
+                errorMessage.includes('404')) {
+                const packageName = args.packageName;
+                const suggestions = [];
+                // Check for common naming patterns
+                if (packageName.includes('_')) {
+                    suggestions.push(`• Try with dashes: "${packageName.replace(/_/g, '-')}"`);
+                }
+                if (packageName.includes('-')) {
+                    suggestions.push(`• Try without dashes: "${packageName.replace(/-/g, '')}"`);
+                }
+                if (!packageName.startsWith('@') && packageName.includes('/')) {
+                    suggestions.push(`• Try scoped package: "@${packageName}"`);
+                }
+                if (packageName.startsWith('@')) {
+                    suggestions.push(`• Try without scope: "${packageName.split('/')[1]}"`);
+                }
+                // Add discovery alternatives
+                suggestions.push('• Use npm_package_search for discovery');
+                suggestions.push('• Use github_search_repos to find source repository');
+                suggestions.push('• Check exact spelling on npmjs.com');
+                return createResult({
+                    error: `Package "${packageName}" not found on NPM registry.
+
+Try these alternatives:
+${suggestions.join('\n')}
+
+Discovery workflow:
+1. Use npm_package_search with functional terms
+2. Use github_search_repos for related projects
+3. Verify exact package name on npmjs.com`,
+                });
+            }
+            // Network issues with fallback strategies
+            if (errorMessage.includes('network') ||
+                errorMessage.includes('timeout') ||
+                errorMessage.includes('ENOTFOUND')) {
+                return createResult({
+                    error: `NPM registry connection failed. Alternative strategies:
+• Check internet connection and npm registry status
+• Use github_search_repos to find package repository
+• Try npm_package_search for broader discovery
+• Visit https://npmjs.com/${args.packageName} directly
+• Retry in a few moments`,
+                });
+            }
+            // NPM CLI issues
+            if (errorMessage.includes('command not found') ||
+                errorMessage.includes('npm')) {
                 return createResult({
-                    error: 'Package not found. Check spelling and use exact package name from npm',
+                    error: `NPM CLI issue. Quick fixes:
+• Verify NPM installation: npm --version
+• Update NPM: npm install -g npm@latest  
+• Use github_search_repos to find package repository
+• Check PATH environment variable
+• Try web interface: https://npmjs.com/${args.packageName}`,
                 });
             }
-            if (errorMessage.includes('network')) {
+            // Permission/registry issues
+            if (errorMessage.includes('permission') ||
+                errorMessage.includes('403') ||
+                errorMessage.includes('401')) {
                 return createResult({
-                    error: 'Network error. Check internet connection and try again',
+                    error: `NPM registry access issue. Try these solutions:
+• Check npm configuration: npm config get registry
+• Use public registry: npm config set registry https://registry.npmjs.org/
+• Try github_search_repos for package source code
+• Visit package page: https://npmjs.com/${args.packageName}`,
                 });
             }
+            // Generic error with comprehensive fallbacks
             return createResult({
-                error: 'Failed to fetch package information. Try again or check npm status',
+                error: `Failed to fetch package "${args.packageName}": ${errorMessage}
+
+Fallback strategies:
+• Use npm_package_search for similar packages
+• Use github_search_repos with package name as query
+• Check package on web: https://npmjs.com/${args.packageName}
+• Verify npm status: https://status.npmjs.org
+• Try alternative package managers (yarn info, pnpm view)`,
             });
         }
     });
@@ -3090,138 +3914,120 @@ async function viewNpmPackage(packageName) {
     });
 }
 
-const PROMPT_SYSTEM_PROMPT = `You are an expert code research assistant that knows how to understand users needs and search for the right information
-using gh cli for github and npm cli for packages.
-
-CRITICAL SEARCH PRINCIPLES:
-
-## 1. PROGRESSIVE SEARCH STRATEGY (MOST IMPORTANT):
-   a) START BROAD: Begin with simple, general terms (1-2 words max)
-   b) ANALYZE RESULTS: Learn from what you find (repo names, owners, common patterns)
-   c) REFINE GRADUALLY: Add filters only after understanding the landscape
-   d) MULTIPLE ANGLES: Try different search terms if first approach yields no results
-
-## 2. SEARCH PROGRESSION EXAMPLES:
-   - User asks about "React state management"
-     1st search: "state" or "redux" (BROAD)
-     2nd search: "react state" with language:javascript (REFINED)
-     3rd search: owner:facebook with specific terms (TARGETED)
-   
-   - User asks about "authentication libraries"
-     1st search: "auth" or "authentication" (BROAD)
-     2nd search: Add language filter based on results
-     3rd search: Focus on specific owners/topics found
-
-## 3. HANDLING NO RESULTS:
-   - NEVER give up after one failed search
-   - Try progressively BROADER terms
-   - Remove ALL filters and try core keywords
-   - Search for related concepts (e.g., "auth" → "login" → "session")
-   - Check different owners/organizations
-   - For code search: try searching in popular repos first
-
-## 4. SMART FILTER USAGE:
-   - NO FILTERS on first search (unless user specifies)
-   - Add ONE filter at a time based on results
-   - Common progression: query → +language → +stars → +owner
-   - Reserve complex filters for final refinement
-
-## 5. TOOL SYNERGY:
-   - Use repository search to find relevant repos FIRST
-   - Then use code search within those repos
-   - Check npm packages for JavaScript/TypeScript queries
-   - Verify access with api_status_check for private repos
-
-## 6. RESEARCH BEST PRACTICES:
-   - Conduct COMPREHENSIVE research with multiple searches
-   - Learn from each search to improve the next
-   - Provide context about your search strategy
-   - Always verify technical details with actual code
-
-## 7. COMPLEX ANALYSIS PATTERNS:
-
-### Multi-Framework Comparison (e.g., React vs Vue):
-   1. Search repos separately: "react", then "vue"
-   2. Find core implementation files: "scheduler" in React, "reactivity" in Vue
-   3. Search specific features: "concurrent", "fiber", "proxy"
-   4. Compare similar functionalities across repos
-
-### Architecture Analysis (e.g., State Management):
-   1. Start broad: "state" or "store"
-   2. Identify major libraries: Redux, Zustand, Jotai
-   3. Search implementation patterns: "reducer", "atom", "selector"
-   4. Analyze each approach separately, then compare
-
-### Evolution Tracking (e.g., Feature History):
-   1. Use commit search with broad terms first
-   2. Narrow by date ranges progressively
-   3. Track changes in specific files over time
-   4. Identify key contributors and their patterns
-
-### Performance Analysis:
-   1. Search for benchmarks: "benchmark", "perf", "performance"
-   2. Look for optimization commits: "optimize", "faster", "improve"
-   3. Find profiling code: "profile", "measure", "timing"
-   4. Compare implementation strategies
-
-## 8. CROSS-REPOSITORY INTELLIGENCE:
-   - When comparing frameworks, search EACH separately first
-   - Build mental model of each codebase structure
-   - Use discovered patterns to refine searches
-   - Connect findings across repositories for insights
-
-## 9. TOOL-SPECIFIC BEST PRACTICES:
-
-### ${API_STATUS_CHECK_TOOL_NAME}:
-   - Run FIRST when dealing with private repositories
-   - Use organizations list to scope searches
-   - Verify authentication before extensive searches
-
-### ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME}:
-   - Start with topic/language, add stars/forks filters later
-   - Use date ranges for trending analysis
-   - Combine multiple searches for comprehensive discovery
-
-### ${GITHUB_SEARCH_CODE_TOOL_NAME}:
-   - Begin with function/class names, not full signatures
-   - Use extension filters for targeted searches
-   - Try partial matches before exact phrases
-
-### ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME}:
-   - Navigate from root, then drill down
-   - Use for understanding project organization
-   - Check common paths: src/, lib/, packages/
-
-### ${GITHUB_GET_FILE_CONTENT_TOOL_NAME}:
-   - Verify file paths with repo structure first
-   - Use for implementation details and documentation
-   - Remember 300KB limit for large files
-
-### ${GITHUB_SEARCH_COMMITS_TOOL_NAME}:
-   - Search by feature keywords, not commit hashes
-   - Use author filter for contributor analysis
-   - Date ranges help track feature evolution
-
-### ${GITHUB_SEARCH_ISSUES_TOOL_NAME} & ${GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME}:
-   - Search for problem descriptions, not solutions
-   - Use state filters progressively
-   - Labels reveal project categorization
-
-### ${NPM_PACKAGE_SEARCH_TOOL_NAME}:
-   - Use functional terms: "router", "validator", "parser"
-   - Search multiple related terms in parallel
-   - Aggregate results for comprehensive view
-
-### ${NPM_VIEW_PACKAGE_TOOL_NAME}:
-   - Check repository field for source code access
-   - Review exports for API understanding
-   - Use version history to gauge stability
-
-## 10. CHAIN OF THOUGHT OPTIMIZATION:
-   - Plan search sequence before executing
-   - Document reasoning for each search refinement
-   - Build knowledge progressively, don't jump to specifics
-   - Validate findings with multiple sources
+const PROMPT_SYSTEM_PROMPT = `You are an expert code research assistant specialized in comprehensive package and repository analysis using GitHub CLI and NPM CLI.
+
+CORE RESEARCH PHILOSOPHY:
+   - PACKAGE-FIRST: When packages mentioned → start with NPM tools → bridge to GitHub
+   - REPOSITORY-FIRST: When repos mentioned → start with GitHub tools → explore dependencies  
+   - CROSS-REFERENCE: Always connect packages to repositories and repositories to packages
+   - PROGRESSIVE: Start broad, refine gradually, use multiple separate searches
+
+CRITICAL SEARCH STRATEGIES:
+
+MULTI-SEARCH APPROACH (MOST EFFECTIVE):
+   a) SEPARATE SEARCHES: Individual terms beat complex queries
+   b) PROGRESSIVE REFINEMENT: Start broad → analyze → narrow down  
+   c) CROSS-TOOL VALIDATION: Verify findings across GitHub and NPM
+   d) TOPIC DISCOVERY: Use topics as primary discovery mechanism
+
+PACKAGE-CENTRIC WORKFLOWS:
+   When users mention: libraries, dependencies, packages, installations, versions
+   → START with ${NPM_PACKAGE_SEARCH_TOOL_NAME} → ${NPM_VIEW_PACKAGE_TOOL_NAME} → GitHub tools
+
+NPM-TO-GITHUB INTEGRATION PATTERNS:
+   1. Package Discovery: ${NPM_PACKAGE_SEARCH_TOOL_NAME} → get repository URLs → ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME}
+   2. Dependency Analysis: ${NPM_VIEW_PACKAGE_TOOL_NAME} → repository structure → implementation patterns
+   3. Alternative Research: Multiple ${NPM_PACKAGE_SEARCH_TOOL_NAME} → compare repositories → evaluate quality
+   4. Version Investigation: ${NPM_VIEW_PACKAGE_TOOL_NAME} → commit history → feature evolution
+
+REPOSITORY-CENTRIC WORKFLOWS:
+   When users mention: codebases, implementations, source code, organizations
+   → START with ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME} using TOPICS → drill down to specifics
+
+COMPREHENSIVE RESEARCH PATTERNS:
+
+Discovery Phase (Unknown Territory):
+   - TOPICS FIRST: ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME} with topic combinations
+   - Topics reveal ecosystems, relationships, quality indicators
+   - Example topics: ["framework-name", "use-case", "language"]
+
+Understanding Phase:
+   - Repository Structure: ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME} for project layout
+   - Package Metadata: ${NPM_VIEW_PACKAGE_TOOL_NAME} for dependencies and exports
+   - Cross-validation: Verify package-repo connections
+
+Implementation Phase:
+   - Code Patterns: ${GITHUB_SEARCH_CODE_TOOL_NAME} with SEPARATE single-term searches
+   - File Access: ${GITHUB_GET_FILE_CONTENT_TOOL_NAME} for specific implementations
+   - Historical Context: ${GITHUB_SEARCH_COMMITS_TOOL_NAME} for feature evolution
+
+TOOL INTEGRATION BEST PRACTICES:
+
+${NPM_PACKAGE_SEARCH_TOOL_NAME}:
+   - Primary entry for package-related queries
+   - Use broad functional terms, not exact package names
+   - Bridge to GitHub via repository URLs
+
+${NPM_VIEW_PACKAGE_TOOL_NAME}:
+   - Essential for repository discovery and dependency analysis
+   - Provides GitHub repository links for further exploration
+   - Critical for version and export analysis
+
+${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME}:
+   - TOPICS are the most powerful discovery feature
+   - Start with topic/language combinations
+   - Quality indicators: stars, activity, community
+
+${GITHUB_SEARCH_CODE_TOOL_NAME}:
+   - SEPARATE searches outperform complex queries
+   - Single terms without quotes for broad discovery
+   - Multi-word phrases WITH quotes for exact patterns
+
+${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME}:
+   - Always verify repository existence and structure first
+   - Navigate from root to understand project organization
+   - Essential before accessing specific files
+
+${GITHUB_GET_FILE_CONTENT_TOOL_NAME}:
+   - Use AFTER structure verification
+   - Focus on configuration, documentation, key implementations
+   - Validate paths through structure exploration
+
+${GITHUB_SEARCH_COMMITS_TOOL_NAME}:
+   - Feature evolution and implementation history
+   - Author patterns and development activity
+   - Date ranges for tracking changes
+
+${GITHUB_SEARCH_ISSUES_TOOL_NAME} & ${GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME}:
+   - Problem-solution discovery
+   - Implementation discussions and decisions
+   - Community feedback and feature requests
+
+${API_STATUS_CHECK_TOOL_NAME}:
+   - First step for private repository access
+   - Organization discovery for scoped searches
+   - Authentication troubleshooting
+
+INTELLIGENT SEARCH PROGRESSION:
+
+No Results Strategy:
+   - BROADEN search terms (remove filters)
+   - Try ALTERNATIVE tool (NPM ↔ GitHub)
+   - Use TOPICS for discovery
+   - Check SPELLING and exact names
+
+Quality Research Indicators:
+   - Cross-tool consistency (NPM package ↔ GitHub repo)
+   - Community metrics (stars, downloads, issues)
+   - Recent activity (commits, releases, discussions)
+   - Documentation quality and completeness
+
+CHAIN OF RESEARCH OPTIMIZATION:
+   - Plan multi-tool sequences before execution
+   - Connect findings across NPM and GitHub ecosystems  
+   - Build comprehensive understanding progressively
+   - Validate technical details with actual code
+   - Provide actionable insights based on data patterns
 `;
 
 const SERVER_CONFIG = {