NovaClip exposes 5 tools via HTTP, but definition quality is severely compromised. Tool names lack action verbs (ai_edit_handler, serve_clip, export_clip are acceptable but inconsistent). Descriptions exist but are generic and lack LLM-optimized guidance on WHEN to use each tool or what happens on failure. Critical gap: input schemas are not visible in the provided source code, only parameter names and types are inferred from the description text. No output schemas documented. The ai_edit_handler tool exposes a Gemini API key as an optional parameter, violating secret-injection patterns. Error handling is absent, no recovery guidance, no categorization of retryable vs fatal errors. Tool composition is weak: ai_edit_handler bundles multiple edit operations (trim, reframe, caption, translate, etc.) into one tool, violating single-responsibility principle.

• Add explicit JSON Schema definitions for all tool inputs. Include type, description, enum constraints, and required fields for each parameter. Example: clip_ids should be array of strings with UUID format constraint.
• Move Gemini API key to server-side environment variable injection. Remove from ai_edit_handler parameters. Document in tool description that API key is auto-injected.
• Split ai_edit_handler into separate single-purpose tools: trim_clip, reframe_clip, add_caption, translate_clip, boost_originality, add_meme_overlay, merge_clips, delete_clip. Each tool should have one clear responsibility.
• Document output schemas for all tools. Specify return types, field names, and structure. Example: serve_clip should document whether it returns {url, stream, metadata} and what fields are included.
• Add error handling guidance to descriptions. Example: 'If clip_id not found, returns 404 with available clip IDs. Retry with correct ID or call list_clips() first.' Categorize errors as retryable or user-fixable.