User: "Add portfolio data to spreadsheet"
Agent: [Tries spreadsheet_set_cell]
System: Error - Spreadsheet not initialized
Agent: "Error: Spreadsheet not initialized"
User: 😕 "What should I do?"

User: "Add portfolio data to spreadsheet"
Agent: [Calls prepare_spreadsheet_workspace first]
Agent: "To add portfolio data, we need a workbook. I recommend creating
       'Portfolio Data Manager'. Would you like me to guide you?"
User: ✅ "Yes!"
Agent: [Guides user through workflow]

import {
  executeToolWithChecks,
  CommonPrerequisites,
  buildToolDescription,
  toolErrorLearning,
} from './tool-intelligence';

const CommonPrerequisites = {
  spreadsheetReady: () => ({
    name: 'spreadsheet_initialized',
    check: () => univerAgentBridge.isReady(),
    failureMessage: 'No spreadsheet is currently loaded',
    remedy: 'User must navigate to a workbook page',
    remedyTool: 'prepare_spreadsheet_workspace',
  }),

  authenticated: (context) => ({
    name: 'user_authenticated',
    check: () => !!context.userId,
    failureMessage: 'User is not authenticated',
    remedy: 'User must be logged in',
  }),

  inDashboardContext: (context) => ({
    name: 'in_dashboard_context',
    check: () => context.workspace?.activeView === 'dashboard',
    failureMessage: 'Not currently viewing a dashboard',
    remedy: 'User must navigate to a dashboard',
    remedyTool: 'update_workspace_context',
  }),
};

class ToolErrorLearning {
  // Tracks error history
  logError(toolName, error, context)

  // Records successful resolutions
  recordResolution(toolName, error, resolution)

  // Provides insights based on patterns
  getErrorInsights(toolName): string[]

  // Suggests fixes based on history
  getSuggestionsForError(toolName, error): string[]
}

async function executeToolWithChecks(
  toolName: string,
  prerequisites: ToolPrerequisite[],
  execute: () => Promise<any>,
  context: ToolExecutionContext
): Promise<ToolExecutionResult>

import {
  executeToolWithChecks,
  CommonPrerequisites,
  buildToolDescription,
  toolErrorLearning,
  type ToolExecutionContext,
} from './tool-intelligence';

// Example: Dashboard tool needs dashboard context
const dashboardPrerequisites = [
  CommonPrerequisites.authenticated(executionContext),
  CommonPrerequisites.databaseConnected(executionContext),
  CommonPrerequisites.inDashboardContext(executionContext),
];

// Example: Spreadsheet tool needs spreadsheet ready
const spreadsheetPrerequisites = [
  CommonPrerequisites.authenticated(executionContext),
  CommonPrerequisites.spreadsheetReady(),
];

my_tool: tool({
  description: 'Does something',
  parameters: z.object({...}),
  execute: async (params) => {
    // Manual checks
    if (!somethingReady) {
      return { error: 'Not ready' };
    }

    // Do the work
    const result = await doWork(params);
    return result;
  },
}),

my_tool: tool({
  description: buildToolDescription(
    'Does something intelligently',
    [CommonPrerequisites.somethingReady()]
  ),
  parameters: z.object({...}),
  execute: async (params) => {
    return executeToolWithChecks(
      'my_tool',
      [CommonPrerequisites.somethingReady()],
      async () => {
        // Do the work
        const result = await doWork(params);

        // Record successful pattern
        if (result.success) {
          toolErrorLearning.recordResolution(
            'my_tool',
            'Common error message',
            'How we fixed it'
          );
        }

        return result;
      },
      executionContext
    );
  },
}),

const learningSummary = generateLearningSummary();
if (learningSummary.length > 50) {
  builder.addSection(learningSummary, 'veryLow', 'Error learnings');
}

// 1. Error occurs
Agent tries: spreadsheet_set_cell
System logs: "Spreadsheet not initialized" (count: 1)

// 2. User corrects by opening workbook
Agent: "User opened workbook"
System: spreadsheet_set_cell now works

// 3. Record resolution
toolErrorLearning.recordResolution(
  'spreadsheet_set_cell',
  'Spreadsheet not initialized',
  'Used prepare_spreadsheet_workspace before attempting operation'
);

// 4. Next time agent sees error
Agent asks: getSuggestionsForError('spreadsheet_set_cell', 'Spreadsheet not initialized')
System returns: ['Used prepare_spreadsheet_workspace before attempting operation']

// 5. Agent learns!
Agent now always calls prepare_spreadsheet_workspace first

const customPrereq: ToolPrerequisite = {
  name: 'data_validation_schema_loaded',
  check: async () => {
    const schema = await loadValidationSchema();
    return !!schema;
  },
  failureMessage: 'Validation schema not loaded',
  remedy: 'Load validation schema from database',
  remedyTool: 'load_validation_schema',
};

const suggestions = getContextualSuggestions(executionContext);
// Returns:
// - "User is not in any specific view - suggest navigating"
// - "Spreadsheet not available - suggest opening workbook if needed"

const insights = toolErrorLearning.getErrorInsights('my_tool');
// Returns:
// - "Recent errors with my_tool: 5 in last 100 calls"
// - "Common issue: 'Not initialized' (occurred 12 times)"
// - "Known fixes: Use prepare_workspace first"

// Test 1: Prerequisite Check
User: "Add data to spreadsheet" (without opening workbook)
Expected: Agent calls prepare_spreadsheet_workspace, guides user

// Test 2: Learning
Agent makes same error twice
Expected: Third time, agent suggests resolution from history

// Test 3: Self-Correction
Agent tries invalid operation
Expected: Error message includes suggestions and remedy tool

executeToolWithChecks(
  toolName: string,
  prerequisites: ToolPrerequisite[],
  execute: () => Promise<any>,
  context: ToolExecutionContext
): Promise<ToolExecutionResult>

buildToolDescription(
  baseDescription: string,
  prerequisites: ToolPrerequisite[]
): string

// Log an error
toolErrorLearning.logError(toolName, error, context)

// Record resolution
toolErrorLearning.recordResolution(toolName, error, resolution)

// Get insights
toolErrorLearning.getErrorInsights(toolName): string[]

// Get suggestions
toolErrorLearning.getSuggestionsForError(toolName, error): string[]

generateLearningSummary(): string
// Returns formatted summary for system prompt

getContextualSuggestions(context: ToolExecutionContext): string[]
// Returns context-aware suggestions