OpenShowreel has 17 well-named tools with clear descriptions and mostly complete schemas. Tool names follow verb_noun convention (ae_create_shape, ae_animate_transform). Descriptions are detailed and contextual (avg ~150 chars, within 10-1024 baseline). However, critical gaps exist: (1) NO output schemas documented for any tool, LLMs cannot predict return structure; (2) parameter descriptions lack validation constraints (e.g., ae_create_shape color accepts [0-1] but no min/max in schema); (3) error handling is absent, no recovery guidance or categorization; (4) ae_eval is a dangerous escape hatch with minimal safeguards. Most tools are READ_ONLY or WRITE but lack explicit idempotency/destructiveness annotations in the schema.

• Document output schema for every tool. Add a 'returns' field to each tool definition: e.g., ae_setup_comp returns {comp_name: string, width: number, height: number, fps: number, duration_seconds: number}. This enables LLMs to chain tools and extract the right fields.
• Add min/max constraints to numeric parameters. Use z.number().min(0).max(1) for colors, z.number().positive() for dimensions, z.number().min(0).max(360) for angles. Zod schema constraints are machine-parseable and prevent invalid LLM inputs.
• Implement structured error responses. Instead of raw ExtendScript errors, catch exceptions and return {error: string, code: string, recovery: string}. E.g., {error: 'Composition not found', code: 'COMP_NOT_FOUND', recovery: 'Call ae_scene_info() to list available compositions.'}
• Restrict ae_eval to read-only mode by default. Add a 'mode' parameter (enum: ['read', 'write']) and require explicit opt-in for write operations. Log all invocations with timestamp, code snippet, and result for audit trails.
• Add tool annotations to the MCP SDK registration. Use readOnlyHint for ae_scene_info, destructiveHint for ae_eval (write mode), and idempotentHint for ae_setup_comp (if comp name already exists, return existing comp). This guides agent retry logic.