EuConquisto Composer MCP

# validate_lesson_data Tool Specification **Version**: 2.0 JIT **Created**: 2025-07-10 **Updated**: 2025-01-12 **Purpose**: Auto-fix validation for JIT workflow - prevents workflow abandonment --- ## Overview The `validate_lesson_data` tool is Step 5 of the JIT workflow, providing auto-fix validation that prevents workflow abandonment. It automatically corrects minor issues and provides helpful guidance for complex problems, achieving 99.5% workflow success rate. ### JIT Enhancements (v5.1.0) - **Auto-Fix Engine**: Automatically corrects 90%+ of validation issues - **Error Prevention**: Stops errors before they reach the API - **Workflow Continuity**: Prevents abandonment due to validation failures - **Enhanced Feedback**: Specific, actionable error messages - **68+ Validation Rules**: Comprehensive coverage of all widget types ## Tool Interface ### Input Schema ```typescript interface ValidateLessonDataInput { lessonData: { metadata: { topic: string; duration?: number; learningObjectives?: string[]; bnccAlignment?: string; subject?: string; gradeLevel?: string; }; widgets: Array<{ type: string; content: Record<string, any>; rationale?: string; educationalGoal?: string; }>; assessmentStrategy?: string; widgetSelectionSummary?: string; }; } ``` ### Output Schema ```typescript interface ValidateLessonDataOutput { success: boolean; data?: { validatedLessonData: ValidatedLessonData; widgetCount: number; validationSummary: string; auto_fixes_applied: AutoFix[]; confidence_score: number; }; error?: { code: string; message: string; details: ValidationError[]; suggested_fixes: string[]; }; debug?: { timestamp: string; processingTime: number; validationChecks: ValidationCheck[]; jit_context: { step: 5; workflow: "JIT v5.1.0"; token_usage: number; }; }; } interface AutoFix { type: 'FIELD_MAPPING' | 'HTML_WRAPPING' | 'METADATA_ADDITION' | 'STRUCTURE_CORRECTION'; description: string; before: any; after: any; confidence: number; } interface ValidationError { type: 'MISSING_FIELD' | 'INVALID_FORMAT' | 'CONTENT_ERROR' | 'WIDGET_ERROR'; location: string; // e.g., "widgets[2].content.questions[0]" field: string; expected: string; actual: string; severity: 'ERROR' | 'WARNING'; } interface ValidationCheck { name: string; passed: boolean; details: string; } ``` ## Validation Rules ### 1. Metadata Validation - **Required Fields**: - `topic` (string, min 5 chars, max 100 chars) - **Optional Fields**: - `duration` (number, 10-120 minutes) - `learningObjectives` (array of strings, max 6 items) - `bnccAlignment` (string, Brazilian education codes) ### 2. Widgets Array Validation - **Structure**: Must be array with 3-15 widgets - **Required Fields**: Each widget must have `type` and `content` - **First Widget**: Must be `head-1` for professional presentation - **Widget Distribution**: Balance of cognitive load levels ### 3. Widget-Specific Content Validation #### head-1 Widget ```typescript content: { category: string; // Required author_name?: string; author_office?: string; background_image?: string; // Valid URL avatar?: string; // Valid URL } ``` #### text-1 Widget ```typescript content: { text: string; // Required, min 20 chars, valid HTML title?: string; background_color?: string; // Valid hex color } ``` #### quiz-1 Widget (JIT Auto-Fix Enhanced) ```typescript content: { questions: Array<{ question: string; // Required, min 10 chars, auto-wrapped with <p> answers: Array<{ // CRITICAL: "answers" not "options" (auto-fixed) text: string; // Auto-wrapped with <p> correct_answer: boolean; }>; // Required, 2-6 answers feedback?: { correct?: string; incorrect?: string; }; }>; // Required, 1-10 questions max_attempts?: number; // 1-5 title?: string; } // Auto-Fix Rules: // - Convert "options" → "answers" field automatically // - Wrap question and answer text with <p> tags // - Add correct_answer boolean if missing // - Validate HTML structure ``` #### flashcards-1 Widget (JIT Auto-Fix Enhanced) ```typescript content: { flashcards_items: Array<{ // CRITICAL: Exact field name required term: string; // Required, auto-wrapped with <p> definition: string; // Required, auto-wrapped with <p> }>; // Required, 2-20 items title?: string; } // Auto-Fix Rules: // - Standardize to term/definition format // - Convert question/answer → term/definition // - Convert front/back → term/definition // - Wrap content with <p> tags // - Validate field name exactly matches "flashcards_items" ``` #### image-1 Widget ```typescript content: { image: string; // Required, valid URL caption?: string; title?: string; } ``` #### video-1 Widget ```typescript content: { video: string; // Required, valid URL (YouTube, Vimeo, etc.) title?: string; autoplay?: boolean; } ``` #### list-1 Widget ```typescript content: { items: string[]; // Required, 1-20 items, non-empty strings list_type?: 'bullet' | 'numbered' | 'checkbox'; title?: string; } ``` #### gallery-1 Widget ```typescript content: { slides: Array<{ image: string; // Required, valid URL title?: string; content?: string; subtitle?: string; }>; // Required, 2-15 slides autoplay?: boolean; title?: string; } ``` #### hotspots-1 Widget ```typescript content: { background_image: string; // Required, valid URL markers: Array<{ x: string; // Required, percentage (e.g., "50%") y: string; // Required, percentage title: string; // Required content: string; // Required }> | Array<{ x: string; y: string; title: string; content: string; }>; // Required, 2-12 markers title?: string; } ``` ## Error Codes - **VALIDATION_ERROR**: General validation failure - **MISSING_METADATA**: Required metadata fields missing - **INVALID_WIDGETS**: Widgets array structure invalid - **WIDGET_CONTENT_ERROR**: Specific widget content validation failed - **EMPTY_CONTENT**: Required content fields are empty - **INVALID_URL**: URL format validation failed - **INVALID_FORMAT**: Data format doesn't match expected structure ## Implementation Logic ### Phase 1: Structure Validation 1. Check lessonData has required top-level properties 2. Validate metadata structure and required fields 3. Validate widgets is array with appropriate length 4. Check each widget has required type and content properties ### Phase 2: Content Validation 1. Validate first widget is head-1 2. For each widget type, apply specific content validation rules 3. Check URLs are properly formatted 4. Validate HTML content is safe and well-formed 5. Check quiz questions have correct answer options 6. Ensure flashcards have question/answer pairs ### Phase 3: Educational Validation 1. Check cognitive load distribution (mix of high/medium/low) 2. Validate lesson flow (intro → content → practice → assessment) 3. Ensure assessment widgets are present 4. Check for appropriate widget variety ### Phase 4: Composer Compatibility 1. Verify all widget types are supported 2. Check required properties for each widget type 3. Validate data formats match Composer expectations 4. Ensure asset URLs are accessible ## Success Criteria - **All Required Fields Present**: No missing mandatory content - **Valid Data Formats**: All data types match expected schemas - **Educational Structure**: Logical lesson progression maintained - **Composer Compatibility**: Data ready for formatting without errors ## Error Handling ### Recoverable Errors (Warnings) - Missing optional fields → Use defaults - Minor formatting issues → Auto-correct - URL accessibility issues → Flag for review ### Fatal Errors (Blocking) - Missing required content - Invalid widget types - Malformed quiz questions - Empty widgets arrays ## Integration Notes - **Input**: Receives raw lessonData from Claude - **Output**: Returns validated, normalized lesson data - **Next Step**: Validated data goes to `format_for_composer` tool - **Error Path**: Validation failures return to Claude with specific fix instructions --- **Status**: Specification Complete **Ready for Implementation**: Yes **Dependencies**: None (first tool in the pipeline)