Spectr MCP exposes a single tool 'generate_spec' with a detailed docstring and well-structured input schema. The tool name is clear and action-oriented (verb_noun), and the description is comprehensive (350+ chars covering WHAT it does, WHEN to use it, and TYPICAL runtime). All input parameters have type declarations and descriptions. However, the output schema is not formally documented, the description says the tool returns an ~80-150KB markdown document inline OR a short summary if output_path is provided, but there's no structured output definition (e.g., no explicit fields like 'status', 'spec_content', 'file_path'). This prevents LLMs from reliably parsing the response and chaining to downstream tools. Additionally, error handling is not explicitly documented, the tool description does not clarify what happens on invalid inputs (e.g., missing ffmpeg, invalid MP4 path, Anthropic API failures, network timeouts). The description also does not address which errors are retryable vs. fatal, and no recovery guidance is provided. For a tool that runs 5 - 10 minutes and can fail for many reasons (bad input, missing dependencies, API quota, network), the lack of error classification is a significant gap. The schema itself is well-formed with appropriate types (string, dict, int) and sensible defaults (max_frames=20, your_app_name defaults to reference_app).

• Formalize the output schema: if output_path is provided, return {"status": "success", "file_path": "...", "spec_size_bytes": ..., "frames_analyzed": ...}. If omitted, return {"status": "success", "spec_content": "...", "spec_size_bytes": ...}. Document both response shapes in the tool description.
• Add explicit error handling to the tool description, e.g.: 'On invalid source path: returns {"error": "file_not_found", "hint": "Ensure source is an absolute path to an .mp4, .mov, or .m4v file"}. On Anthropic API errors: returns {"error": "api_error", "hint": "Verify ANTHROPIC_API_KEY is set or claude CLI is available. This error is retryable."}. On timeout (>15 min): returns {"error": "timeout", "hint": "Pipeline took too long. Try reducing max_frames to 15-20 and retry."}.'
• Clarify progress handling in the tool description: 'During execution, the server sends progress notifications every 25 seconds (frame extraction → analysis → spec generation). The LLM should expect multiple intermediate messages before the final result.'
• Constrain 'brand_colors' parameter: change type to object with pattern-validated string values. Example: {"type": "object", "additionalProperties": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"}, "maxProperties": 5}. Update description to: 'Optional dict of brand color overrides (e.g., {"primary": "#FF5722", "secondary": "#2196F3"}). Keys are color role names (primary, secondary, accent, etc.); values must be hex color codes (#RRGGBB). Max 5 colors.'
• Document max_frames more precisely in the tool description. Current text says 'each +10 frames roughly +50% vision cost' but does not clarify practical limits. Add: 'Recommended range: 15 - 30. Values >48 may cause API quota issues. For simpler apps (few distinct screens), default 20 usually sufficient.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry