CodeVideo MCP exhibits significant quality gaps across naming, descriptions, and schema documentation. While 26 tools are registered, most lack complete parameter type definitions and many descriptions are generic or missing critical context. Tool names are verbose and inconsistent in verb usage. Parameter schemas are frequently incomplete, many lack explicit 'type' fields, and object/array parameters (e.g., 'lesson', 'actions') have no itemized schema documentation. Several tools accept optional parameters with redundant dual-input patterns (actions array OR previously stored actions) that increase cognitive load. Error handling guidance is absent from all tool descriptions. The server uses STDIO transport, which is not remotely accessible and caps protocol readiness at 50 regardless of other factors.
Object and array parameters lack itemized schema documentation. Tools like 'codevideo_add_actions_to_lesson' accept 'actions' (array) and 'lesson' (object) with no visible type specifications for nested fields. LLMs cannot reason about structure without schema details.
Tool names are excessively long and lack consistent verb-noun structure. Names like 'codevideo_instructions_to_create_a_course' (50 chars) are verbose; standard conventions favor 'create_course' (13 chars). Inconsistent prefixes and noun forms (get_/make_) across similar operations increase disambiguation overhead.
Rename tools to follow verb_noun convention with ~15-25 character names. Replace 'codevideo_instructions_to_create_a_course' with 'create_course_instructions', 'codevideo_make_video_from_actions' with 'generate_video', etc. This aligns with the 90% baseline of A+ tools starting with action verbs.
Document return types for every tool. Add a 'Returns' section to each description: 'Returns: object with fields: course_id (string), name (string), description (string), lessons (array of ILesson objects)'. This enables agents to chain tools and extract relevant data.
Expand parameter descriptions to 50-100 characters each, including constraint details. Example: 'targetLanguage: Target language for translation. Valid values: Spanish, French, German, Portuguese, Chinese, Japanese. Case-insensitive.' This matches the 72-char baseline for param annotations.
Consolidate the dual-input pattern (explicit param OR stored state) into a single clear mechanism. Either: (a) require explicit input always, or (b) introduce a 'use_stored' boolean param that clarifies intent. Document the precedence rule explicitly.
Add error recovery guidance to tool descriptions. Example: 'If translation fails due to unsupported language, try a similar language or fallback to English. Call get_supported_languages() to discover valid options.'
Fix the typo: rename 'codevideo_critiqu_video_using_gemini' to 'codevideo_critique_video_using_gemini'.
Introduce enum constraints for string parameters where applicable. For 'targetLanguage', use an enum: ['Spanish', 'French', 'German', 'Portuguese', 'Chinese', 'Japanese'] instead of free-form string.
Get the final state snapshot after applying CodeVideo actions. Pass actions array OR use previously stored actions from codevideo_set_current_actions (recommended workflow).
Generate translation instructions for CodeVideo actions. Pass actions array OR use previously stored actions from codevideo_set_current_actions (recommended workflow).
Redundant dual-input pattern across 7 tools: many accept both an explicit input array/object AND optional previous state (e.g., 'actions OR previously stored actions'). This ambiguous contract forces LLMs to reason about precedence and increases failure modes. Should use single, clear parameter or separate tools.
Most tool descriptions lack context for when/why to select them. Descriptions like 'Generate instructions for creating a course' (41 chars) do not explain WHEN to call this tool instead of another, what prerequisites exist, or what the LLM should do with the output. This violates the 50-200 char LLM-optimized range and omits selection guidance.
Zero output schema documentation. No tool descriptions specify return types, field names, or structure. Agents cannot plan downstream tool calls or extract relevant data without knowing what fields to expect. This is a violation of the 100% baseline for A+ tools.
No error handling guidance in any tool description. None explain what the LLM should do if the call fails, whether errors are retryable, or how to recover. This violates the pattern:recovery-guide and pattern:error-classification requirements.
Typo in tool name: 'codevideo_critiqu_video_using_gemini' should be 'codevideo_critique_video_using_gemini'. Typos in tool names degrade LLM discoverability and appear unprofessional.
Parameter descriptions are generic and lack constraint details. For example, 'additionalContext' in several tools is described only as 'Additional context for X' without explaining valid format, length limits, or how it influences the output. The baseline expectation is descriptions that include format, range, and allowed values.
Add pagination support to tools returning lists (e.g., get_example_actions_array_by_keyword). Include 'limit' and 'offset' parameters and return a 'total_count' field. This prevents context window exhaustion.
Expand descriptions for discovery/inspection tools (get_action_names, get_example_*). Explain what the agent should do with the results: 'Use this to discover available actions before constructing your action array. Pass the action names to validate_actions().'
For tools that accept complex objects (lesson, actions), add inline schema examples in the description or parameter annotation to clarify expected structure.
Add success/failure indicators to tools that perform batch operations (validate_actions). Return per-item success/failure instead of a blanket pass/fail.
Implement proper result pagination and limits. Cap list results at 20-50 items by default to prevent context window exhaustion. Offer pagination for larger result sets.