AE-MCP exhibits pervasive gaps in parameter descriptions, output schema documentation, and error handling guidance. While 14 tools are defined with names and basic input schemas, most lack the LLM-optimized descriptions, enumerated constraints, and actionable error guidance required for production use. Tool names are generally verb-driven (ae_add_*, ae_apply_*, ae_create_*, ae_modify_*), which is positive, but parameter descriptions are often incomplete or generic. Output schemas are entirely absent from documentation, the implementation provides no insight into what each tool returns, forcing LLMs to guess at the response structure. Error handling is not documented at all. Several tools accept open-ended object parameters (e.g., 'effect_parameters', 'properties') without describing valid keys, types, or constraints, inviting hallucinated values. The ae_script tool is a particular risk: it accepts arbitrary JavaScript/ExtendScript with no validation, sandboxing, or scope documentation. Overall, this server would require substantial work before deployment to production agents.
Output schemas completely undocumented. No tool documents what it returns, its fields, or types. LLMs cannot plan downstream tool calls or extract chaining IDs (e.g., layer_id returned by ae_add_text_layer to pass to ae_modify_layer).
Parameters with open-ended object type lack enumeration or key documentation. 'effect_parameters' in ae_apply_effect and 'properties' in ae_modify_layer accept arbitrary key-value pairs with no schema. LLMs will hallucinate keys that do not exist in the After Effects API.
ae_apply_effectae_modify_layerae_modify_text
Recommendations
Document output schemas for all 14 tools. For each tool, explicitly declare return type (object or array), required fields, field types, and descriptions. Example: ae_create_composition returns {composition_id: string, name: string, width: number, height: number, duration: number, frame_rate: number}. Use JSON Schema format.
Replace open-ended object parameters with enumerated or documented schemas. For ae_apply_effect, either (a) list all supported effects and their valid parameters in the description, or (b) split into tool-specific variants like ae_apply_blur, ae_apply_color_correction. Same for ae_modify_layer and ae_modify_text.
Add formal enum constraints to camera_type (ae_add_camera_layer), light_type (ae_add_light_layer), shape_type (ae_add_preset_shape_layer), and action (ae_project). Use JSON Schema 'enum' field, do not rely on description text alone.
Expand tool descriptions to 100-200 characters with context. Example: ae_get_effect_categories -> 'List all effect categories available in After Effects (e.g., Blur, Distort, Light). Call this to discover categories before using ae_get_effects_by_category to list specific effects within a category.'
Add error handling guidance to each tool description. Example: ae_create_composition -> 'If the composition name conflicts with an existing composition, returns error COMPOSITION_NAME_EXISTS. Try a different name or call ae_project (action=get) to list existing compositions.'
ae_script accepts arbitrary script_content with no validation, sandboxing, or scope documentation. This is a severe security risk and operational hazard, LLMs could inject malicious ExtendScript that deletes project data, exports sensitive information, or crashes After Effects. No permission gates, input sanitization, or audit trail mentioned.
Most tool descriptions are under 50 characters and generic. E.g., ae_get_effect_categories: 'Get available effect categories in After Effects' (55 chars) provides no context on WHEN to call it, what the response structure is, or how to chain to ae_get_effects_by_category.
No error handling guidance documented anywhere. Tools have no descriptions of retryable vs fatal errors, no recovery hints (e.g., 'If composition_name not found, call ae_project to list available compositions'), and no actionable error messages. LLMs cannot determine next steps on failure.
Numeric parameters lack bounds or constraints. width/height in ae_add_preset_shape_layer and ae_add_solid_layer have no min/max. LLMs could pass negative, zero, or absurdly large values (e.g., 999999999 pixels), causing failures or resource exhaustion. No validation guidance in descriptions.
Color parameters accept arrays [R, G, B] with 0-1 range but have no validation logic documented. ae_add_light_layer and ae_add_solid_layer both accept color arrays, what happens if an LLM passes [256, 256, 256] (0-255 range instead of 0-1)? No error handling guidance.
Enumeration constraints not declared for known-value parameters. camera_type in ae_add_camera_layer says 'One-Node Camera, Two-Node Camera' in the description but has no enum in the schema. LLMs may pass 'single-node-camera' or 'TwoNodeCamera' (case variation or format mismatch). Must use formal enum constraint.
Parameters mcp_aftereffects_ae_add_custom_shape_layer (vertices, in_tangents, out_tangents, feather_radii) are declared as 'array' type but lack item type descriptors. Are items numbers? Objects? The description says 'Array of points...as [[x1,y1], [x2,y2], ...]' but the schema does not formally specify that items are 2-element arrays. LLMs must guess the structure.
No parameter documentation for ae_project 'action' parameter. What are valid values? (get, save, close, export, render, etc.?) The description says 'Action to perform (get, save, close, etc.)' with 'etc.' implying there are more, but the tool is useless without a full enum. Undocumented dependencies.
No pagination, limit, or batch support. If ae_get_effects_by_category returns hundreds of effects, the response could blow the context window. No documented limit, no pagination parameters (page, limit, offset), no guidance on result size.
tool name 'mcp_aftereffects_ae_add_custom_shape_layer' is inconsistent. Other tools use 'ae_*' prefix, but this one uses 'mcp_aftereffects_ae_*'. Inconsistent naming confuses LLMs when disambiguating similar tools. All tools should use canonical prefix (ae_*) consistently.
mcp_aftereffects_ae_add_custom_shape_layer
Add item type schemas to array parameters. For mcp_aftereffects_ae_add_custom_shape_layer vertices, in_tangents, out_tangents, feather_radii, declare: type array, items type array, items type number (for point coordinates). Formally specify that vertices is array of 2-element arrays [[x, y], ...].
Add validation and error messages for color array parameters. When LLM passes color values outside 0-1 range, return: 'Invalid color: got [R, G, B] = [X, Y, Z]. Values must be in range 0.0-1.0. Example: [1.0, 0.5, 0.0] for orange.'
Document pagination for discovery tools. Add to ae_get_effects_by_category: 'Returns up to 50 effects per call. If the category contains more than 50 effects, add limit and offset parameters (limit: 1-100, offset: 0+) to paginate results. Response should include total_count and has_more fields.'
Implement and document input validation. All tools should validate parameters early and return structured errors with the invalid value, constraint violated, and suggestion. Example: 'Invalid camera_type: got "TwoNodeCamera". Must be one of: "One-Node Camera", "Two-Node Camera".'
Standardize tool naming to 'ae_*' prefix. Rename mcp_aftereffects_ae_add_custom_shape_layer to ae_add_custom_shape_layer for consistency.
CRITICAL: Remove or sandbox ae_script tool. Arbitrary script execution is an operational and security hazard. Options: (a) Remove entirely, (b) Whitelist safe APIs only (e.g., read-only queries, no delete/export), (c) Require explicit user confirmation before execution, (d) Execute in a timeout-enforced sandbox with resource limits.
Add tool annotations (tool-use hints) via MCP protocol. Mark destructive tools (ae_add_*, ae_apply_*, ae_modify_*, ae_script) with destructiveHint: true. Mark read-only tools (ae_get_*) with readOnlyHint: true. Mark idempotent operations (ae_create_composition with same name) with idempotentHint: true.
Add dependency hints. Example: ae_modify_layer description -> 'Requires composition_name and layer_name. If you only have the layer_id, call ae_get_composition_layers(composition_name) first to find the layer_name. Then call this tool.'
Add mutual exclusivity notes where applicable. Example: if ae_modify_layer accepts both 'layer_name' and 'layer_index', state: 'Provide either layer_name (string) or layer_index (number), not both. If you have only the index, you must look up the name first via ae_get_composition_layers.'
Document confirmation/dry-run pattern for destructive operations. Suggest: 'For high-risk operations (e.g., ae_script, large ae_modify_layer), consider adding a dry_run parameter (boolean, default false) to preview changes before committing. This prevents agents from accidentally destroying work.'
Ensure tool composition enables chaining. If ae_create_composition returns composition_id, all subsequent tools should accept composition_id, not just composition_name. This reduces lookup calls and context loss between turns.