HashPilot

Instructions

Implementation Reference

• src/tools/error-analysis.ts:59-190 (handler)

  The primary handler function executing the 'error_explain' tool logic. It handles error code lookups, message analysis, category listings, keyword searches, and provides debugging guidance using the Hedera error database.
  export async function errorExplain(args: { errorCode?: string; errorMessage?: string; category?: ErrorInfo['category']; search?: string; }): Promise<{ success: boolean; data?: any; error?: string }> { try { // If category specified, list all errors in that category if (args.category) { const categoryErrors = getErrorsByCategory(args.category); return { success: true, data: { category: args.category, errorCount: categoryErrors.length, errors: categoryErrors.map((e) => ({ code: e.code, name: e.name, description: e.description, solution: e.solution, })), }, }; } // If search specified, search errors by keyword if (args.search) { const results = searchErrors(args.search); return { success: true, data: { searchTerm: args.search, resultCount: results.length, results: results.map((e) => ({ code: e.code, name: e.name, description: e.description, solution: e.solution, })), }, }; } // If error message provided, analyze it if (args.errorMessage) { const analysis = analyzeError(args.errorMessage); return { success: true, data: { originalError: analysis.originalError, detectedCode: analysis.errorCode, severity: analysis.severity, explanation: analysis.errorInfo ? { name: analysis.errorInfo.name, description: analysis.errorInfo.description, cause: analysis.errorInfo.cause, solution: analysis.errorInfo.solution, category: analysis.errorInfo.category, } : null, guidance: analysis.guidance, securityRecommendations: analysis.securityRecommendations, optimizationSuggestions: analysis.optimizationSuggestions, relatedErrors: analysis.relatedErrors, }, }; } // If error code provided, look it up directly if (args.errorCode) { const errorInfo = getErrorInfo(args.errorCode); if (!errorInfo) { // Try to find similar errors const similar = searchErrors(args.errorCode); return { success: false, error: `Error code "${args.errorCode}" not found in database.`, data: { suggestion: 'Try one of these similar errors:', similarErrors: similar.slice(0, 5).map((e) => e.code), availableCategories: ['account', 'token', 'contract', 'consensus', 'network', 'transaction', 'key'], }, }; } return { success: true, data: { code: errorInfo.code, name: errorInfo.name, description: errorInfo.description, cause: errorInfo.cause, solution: errorInfo.solution, category: errorInfo.category, relatedErrors: getErrorsByCategory(errorInfo.category) .filter((e) => e.code !== errorInfo.code) .slice(0, 3) .map((e) => e.code), }, }; } // No input provided - return available error codes summary const categories = ['account', 'token', 'contract', 'consensus', 'network', 'transaction', 'key'] as const; const summary = categories.map((cat) => ({ category: cat, count: getErrorsByCategory(cat).length, })); return { success: true, data: { message: 'Provide an errorCode, errorMessage, category, or search term', totalErrorCodes: Object.keys(HEDERA_ERROR_CODES).length, categorySummary: summary, exampleUsage: [ { errorCode: 'INSUFFICIENT_PAYER_BALANCE' }, { errorMessage: 'Status: TOKEN_NOT_ASSOCIATED_TO_ACCOUNT' }, { category: 'token' }, { search: 'balance' }, ], }, }; } catch (error) { return { success: false, error: error instanceof Error ? error.message : 'Failed to analyze error', }; } }
• src/tools/error-analysis.ts:18-54 (schema)

  The tool definition object containing the name 'error_explain', detailed description, usage examples, and input schema for parameter validation.
  export const errorAnalysisToolDefinition = { name: 'error_explain', description: `Explain Hedera error codes and provide debugging guidance. USE FOR: - Understanding cryptic Hedera error codes (e.g., INSUFFICIENT_PAYER_BALANCE) - Getting step-by-step solutions for common errors - Finding related errors and security recommendations EXAMPLES: - "What does INSUFFICIENT_PAYER_BALANCE mean?" - "Explain TOKEN_NOT_ASSOCIATED_TO_ACCOUNT error" - "I got CONTRACT_REVERT_EXECUTED - what's wrong?" - "List all token-related errors"`, inputSchema: { type: 'object', properties: { errorCode: { type: 'string', description: 'Hedera error code to explain (e.g., INSUFFICIENT_PAYER_BALANCE, TOKEN_NOT_ASSOCIATED_TO_ACCOUNT)', }, errorMessage: { type: 'string', description: 'Full error message to analyze (will extract error code automatically)', }, category: { type: 'string', enum: ['account', 'token', 'contract', 'consensus', 'network', 'transaction', 'key', 'file'], description: 'List all errors in a specific category', }, search: { type: 'string', description: 'Search errors by keyword', }, }, }, };
• src/index.ts:529-531 (registration)

  Registration of the error_explain tool by including its definition in the optimizedToolDefinitions array, which is returned by ListToolsRequestSchema handler.
  // Error Analysis (1 tool - 50+ error codes with debugging guidance) errorAnalysisToolDefinition, ];
• src/index.ts:665-668 (registration)

  Dispatch registration in the main tool execution switch statement, mapping 'error_explain' calls to the errorExplain handler function.
  // Error Analysis case 'error_explain': result = await errorExplain(args as any); break;