Prompt Auto-Optimizer MCP

# Legacy Tools Reference This document provides specifications for legacy GEPA MCP tools maintained for backward compatibility. These tools provide simplified interfaces for common operations but are superseded by the core GEPA tools for new implementations. ## Table of Contents - [gepa_evolve_prompt](#gepa_evolve_prompt) - [gepa_analyze_prompt](#gepa_analyze_prompt) - [gepa_optimize_prompt](#gepa_optimize_prompt) - [gepa_generate_variants](#gepa_generate_variants) > **⚠️ Deprecation Notice**: These tools are maintained for backward compatibility but are considered legacy. New implementations should use the [Core Tools](./core-tools.md) for full GEPA functionality. --- ## gepa_evolve_prompt **Status**: 🟡 Legacy - Use `gepa_start_evolution` + `gepa_evaluate_prompt` + `gepa_select_optimal` for new implementations Legacy tool for evolving prompts using genetic algorithms with simplified parameter interface. ### Purpose Provides a single-call interface for basic prompt evolution without the advanced features of the full GEPA workflow (trajectory recording, reflection analysis, Pareto optimization). ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `prompt` | `string` | ✅ | Initial prompt to evolve | | `fitness_criteria` | `string` | ✅ | Description of fitness evaluation criteria | | `generations` | `number` | ❌ | Number of evolution generations (default: 10) | | `population_size` | `number` | ❌ | Population size per generation (default: 20) | ### Request Example ```typescript const response = await mcpClient.callTool('gepa_evolve_prompt', { prompt: 'Create a function that calculates the factorial of a number', fitness_criteria: 'Code correctness, readability, and efficiency', generations: 15, population_size: 25 }); ``` ### Response Example ```markdown # Genetic Prompt Evolution Results ## Original Prompt Create a function that calculates the factorial of a number ## Best Evolved Prompt Optimized: Create a function that calculates the factorial of a number (with focus on Code correctness, readability, and efficiency) ## Evolution Metrics - **Final Fitness Score**: 0.85 - **Generations**: 15 - **Population Size**: 25 - **Fitness Criteria**: Code correctness, readability, and efficiency ## Evolution History - Generation 1: 0.42 - Generation 7: 0.67 - Generation 15: 0.85 ``` ### Migration to Core Tools **Legacy Approach:** ```typescript const result = await mcpClient.callTool('gepa_evolve_prompt', { prompt: 'original prompt', fitness_criteria: 'criteria', generations: 10 }); ``` **Modern Approach:** ```typescript // 1. Start evolution const evolution = await mcpClient.callTool('gepa_start_evolution', { taskDescription: 'criteria', seedPrompt: 'original prompt', config: { generations: 10 } }); // 2. Evaluate candidates (would be done iteratively) const evaluation = await mcpClient.callTool('gepa_evaluate_prompt', { promptId: 'candidate_id', taskIds: ['task_1'] }); // 3. Select optimal result const optimal = await mcpClient.callTool('gepa_select_optimal', { taskContext: 'criteria' }); ``` ### Limitations - No trajectory recording for reflection analysis - No Pareto frontier optimization - Limited customization options - Simplified fitness evaluation - No component recovery features --- ## gepa_analyze_prompt **Status**: 🟡 Legacy - Use external analysis tools or custom reflection analysis for detailed insights Legacy tool for analyzing prompt structure and providing basic improvement suggestions. ### Purpose Provides basic prompt analysis including metrics calculation, content analysis, and generic improvement suggestions without the sophisticated failure pattern recognition of the reflection engine. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `prompt` | `string` | ✅ | Prompt text to analyze | | `analysis_type` | `string` | ❌ | Type of analysis: 'structure', 'semantic', 'performance', 'all' (default: 'all') | ### Request Example ```typescript const response = await mcpClient.callTool('gepa_analyze_prompt', { prompt: 'Write a Python function that implements binary search on a sorted array. Include error handling and documentation.', analysis_type: 'all' }); ``` ### Response Example ```markdown # Prompt Analysis Results ## Basic Metrics - **Word Count**: 17 - **Character Count**: 108 - **Sentence Count**: 2 - **Complexity Score**: 1.08 - **Readability Score**: 0.73 ## Content Analysis - **Key Phrases**: Python, function, implements, binary, search - **Sentiment**: neutral ## Improvement Suggestions - Consider adding more specific examples - Define technical terms clearly - Structure with bullet points for better readability ## Original Prompt ``` Write a Python function that implements binary search on a sorted array. Include error handling and documentation. ``` ``` ### Analysis Types | Type | Description | Output | |------|-------------|--------| | `structure` | Basic structure metrics | Word count, sentences, complexity | | `semantic` | Content and meaning analysis | Key phrases, sentiment, entities | | `performance` | Effectiveness indicators | Readability, clarity scores | | `all` | Complete analysis | All metrics and suggestions | ### Migration to Core Tools **Legacy Approach:** ```typescript const analysis = await mcpClient.callTool('gepa_analyze_prompt', { prompt: 'prompt text', analysis_type: 'all' }); ``` **Modern Approach:** ```typescript // Use reflection analysis with trajectory data const reflection = await mcpClient.callTool('gepa_reflect', { trajectoryIds: ['trajectory_1', 'trajectory_2'], targetPromptId: 'prompt_id', analysisDepth: 'deep' }); // Or implement custom analysis using external tools // (NLP libraries, prompt analysis frameworks, etc.) ``` ### Limitations - Static analysis only (no execution data) - Generic improvement suggestions - Limited semantic understanding - No failure pattern recognition - No performance correlation analysis --- ## gepa_optimize_prompt **Status**: 🟡 Legacy - Use `gepa_reflect` with trajectory-based insights for intelligent optimization Legacy tool for optimizing prompts based on specific targets with rule-based transformations. ### Purpose Applies predefined optimization rules to improve prompts for specific targets (length, clarity, effectiveness, specificity) without the intelligent, data-driven approach of reflection-based optimization. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `prompt` | `string` | ✅ | Prompt to optimize | | `optimization_target` | `string` | ✅ | Target: 'length', 'clarity', 'effectiveness', 'specificity' | | `constraints` | `object` | ❌ | Optimization constraints (optional) | ### Optimization Targets | Target | Description | Optimization Strategy | |--------|-------------|----------------------| | `length` | Reduce prompt verbosity | Remove redundant words, simplify structure | | `clarity` | Improve understandability | Add clear instructions, improve flow | | `effectiveness` | Enhance task performance | Add examples, specify requirements | | `specificity` | Increase precision | Add constraints, clarify expectations | ### Request Example ```typescript const response = await mcpClient.callTool('gepa_optimize_prompt', { prompt: 'Please write some code that does sorting and make it work well and be readable', optimization_target: 'specificity', constraints: { max_length: 200, preserve_keywords: ['sorting', 'readable'], maintain_tone: true } }); ``` ### Response Example ```markdown # Prompt Optimization Results ## Optimization Target specificity ## Original Prompt ``` Please write some code that does sorting and make it work well and be readable ``` ## Optimized Prompt ``` Please write some code that does sorting and make it work well and be readable Requirements: - Be specific - Include examples - Explain your reasoning ``` ## Applied Optimizations - Target: specificity - Constraints: {"max_length":200,"preserve_keywords":["sorting","readable"],"maintain_tone":true} - Improvement Score: 0.78 ``` ### Constraint Options ```typescript interface OptimizationConstraints { max_length?: number; // Maximum character count min_length?: number; // Minimum character count preserve_keywords?: string[]; // Keywords to maintain maintain_tone?: boolean; // Preserve original tone add_examples?: boolean; // Include example usage structure_format?: 'bullet' | 'numbered' | 'paragraph'; } ``` ### Migration to Core Tools **Legacy Approach:** ```typescript const optimized = await mcpClient.callTool('gepa_optimize_prompt', { prompt: 'original prompt', optimization_target: 'effectiveness' }); ``` **Modern Approach:** ```typescript // 1. Record trajectories with current prompt await mcpClient.callTool('gepa_record_trajectory', { promptId: 'current_prompt', taskId: 'task_1', // ... execution details }); // 2. Analyze failures and get specific improvements const reflection = await mcpClient.callTool('gepa_reflect', { trajectoryIds: ['trajectory_1', 'trajectory_2'], targetPromptId: 'current_prompt', focusAreas: ['instruction_clarity', 'example_quality'] }); // 3. Apply data-driven improvements based on analysis ``` ### Limitations - Rule-based optimization only - No learning from execution data - Limited optimization strategies - Generic improvement patterns - No performance validation --- ## gepa_generate_variants **Status**: 🟡 Legacy - Use genetic evolution with `gepa_start_evolution` for intelligent variant generation Legacy tool for generating prompt variants using predefined strategies without evolutionary intelligence. ### Purpose Creates multiple prompt variations using simple transformation strategies, superseded by genetic algorithm-based variant generation that learns from performance data. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `prompt` | `string` | ✅ | Base prompt for variant generation | | `variant_count` | `number` | ❌ | Number of variants to generate (default: 5) | | `strategy` | `string` | ❌ | Generation strategy: 'mutation', 'crossover', 'template', 'semantic' (default: 'mutation') | ### Generation Strategies | Strategy | Description | Example Transformation | |----------|-------------|----------------------| | `mutation` | Small modifications to original | Add specificity hints | | `crossover` | Combine with template patterns | Merge with best practices | | `template` | Apply structured templates | Convert to step-by-step format | | `semantic` | Synonym replacement | Replace verbs with alternatives | ### Request Example ```typescript const response = await mcpClient.callTool('gepa_generate_variants', { prompt: 'Create a REST API endpoint for user authentication', variant_count: 6, strategy: 'template' }); ``` ### Response Example ```markdown # Prompt Variants Generated ## Base Prompt ``` Create a REST API endpoint for user authentication ``` ## Strategy template ## Generated Variants ### Variant 1 (Fitness: 0.74) ``` Create a REST API endpoint for user authentication (Variation 1: with enhanced specificity) ``` ### Variant 2 (Fitness: 0.68) ``` Hybrid approach: Create a REST API endpoint for user authentication - incorporating best practices ``` ### Variant 3 (Fitness: 0.81) ``` Template-based: Please create a rest api endpoint for user authentication following these steps: 1) Analyze, 2) Execute, 3) Verify ``` ### Variant 4 (Fitness: 0.72) ``` Create a REST API endpoint for user authentication (Variation 4: with enhanced specificity) ``` ### Variant 5 (Fitness: 0.76) ``` Hybrid approach: Create a REST API endpoint for user authentication - incorporating best practices ``` ### Variant 6 (Fitness: 0.69) ``` Template-based: Please create a rest api endpoint for user authentication following these steps: 1) Analyze, 2) Execute, 3) Verify ``` ``` ### Strategy Details #### Mutation Strategy - Adds specificity markers - Inserts clarification phrases - Modifies instruction tone - Includes context hints #### Crossover Strategy - Combines with successful patterns - Merges domain best practices - Applies hybrid approaches - Incorporates proven templates #### Template Strategy - Applies structured formats - Converts to step-by-step - Adds requirement sections - Includes example placeholders #### Semantic Strategy - Replaces synonyms strategically - Varies technical terminology - Adjusts formality level - Modifies action verbs ### Migration to Core Tools **Legacy Approach:** ```typescript const variants = await mcpClient.callTool('gepa_generate_variants', { prompt: 'base prompt', variant_count: 5, strategy: 'mutation' }); ``` **Modern Approach:** ```typescript // 1. Start evolution with base prompt const evolution = await mcpClient.callTool('gepa_start_evolution', { taskDescription: 'task description', seedPrompt: 'base prompt', config: { populationSize: 20 } }); // 2. Evolution automatically generates intelligent variants // 3. Evaluate variants with real performance data const evaluation = await mcpClient.callTool('gepa_evaluate_prompt', { promptId: 'variant_id', taskIds: ['task_1', 'task_2'] }); // 4. Select best performing variants const optimal = await mcpClient.callTool('gepa_get_pareto_frontier', { limit: 5 }); ``` ### Limitations - No performance-based learning - Predefined transformation rules - No adaptation to task context - Limited diversity strategies - No fitness validation --- ## Migration Guide ### From Legacy to Core Tools | Legacy Tool | Core Replacement | Benefits | |-------------|------------------|----------| | `gepa_evolve_prompt` | `gepa_start_evolution` + workflow | Trajectory recording, reflection analysis | | `gepa_analyze_prompt` | `gepa_reflect` | Data-driven insights, failure patterns | | `gepa_optimize_prompt` | Reflection-based optimization | Performance-driven improvements | | `gepa_generate_variants` | Genetic evolution | Intelligent variant generation | ### Migration Steps 1. **Replace Single-Call Tools** ```typescript // Old: Single legacy call const result = await legacyTool(params); // New: Workflow-based approach const evolution = await startEvolution(params); const evaluation = await evaluatePrompt(candidates); const optimal = await selectOptimal(criteria); ``` 2. **Add Trajectory Recording** ```typescript // Record execution data for analysis await recordTrajectory({ promptId: 'candidate_id', taskId: 'task_id', executionSteps: steps, result: outcome }); ``` 3. **Implement Reflection Analysis** ```typescript // Use data-driven improvement suggestions const reflection = await reflect({ trajectoryIds: ['traj_1', 'traj_2'], targetPromptId: 'prompt_id' }); ``` 4. **Enable Multi-Objective Optimization** ```typescript // Leverage Pareto frontier for balanced optimization const frontier = await getParetoFrontier({ minPerformance: 0.7, limit: 10 }); ``` ### Backward Compatibility Legacy tools remain available for existing integrations but: - Are not actively enhanced with new features - May be deprecated in future major versions - Should be replaced in new implementations - Provide warnings about deprecated usage ### Recommended Timeline - **Immediate**: Use core tools for new features - **Short-term (3 months)**: Plan migration of critical workflows - **Medium-term (6 months)**: Complete migration to core tools - **Long-term (12 months)**: Remove legacy tool dependencies ## Support for Legacy Tools ### Documentation - Legacy tools are documented for reference - Migration examples provided for each tool - Best practices focus on core tool adoption ### Bug Fixes - Critical security issues will be addressed - Major functional bugs may be fixed - New feature requests will be declined ### Community Support - Community forums available for migration questions - Example repositories show modern implementations - Migration scripts may be provided by community --- ## Conclusion While legacy tools provide simplified interfaces for basic GEPA functionality, the core tools offer significantly enhanced capabilities through: - **Data-Driven Intelligence**: Learning from execution trajectories - **Multi-Objective Optimization**: Balanced performance vs. diversity optimization - **Resilience Features**: Comprehensive backup and recovery capabilities - **Reflection-Based Improvement**: Intelligent failure analysis and suggestions For optimal results and future compatibility, migrate to the core GEPA tool ecosystem that provides a more sophisticated and capable prompt optimization platform.