Server defines 3 image generation/manipulation tools with generally good schemas and descriptions. Tool names are action-oriented (create-, edit-, varies-), which is appropriate. All three tools have detailed parameter schemas with proper JSON Schema typing. However, there are several quality gaps: (1) Output schemas are not documented, the return type structure is unclear from the tool definitions, making it hard for LLMs to plan downstream actions; (2) Error handling is minimal, no guidance on recovery paths, retryability, or user-fixable vs fatal errors; (3) Descriptions, while present, focus on API parameters rather than when/why to use each tool; (4) No tool annotations (destructiveHint, readOnlyHint, idempotentHint) despite all three tools being write operations (WRITE risk declared); (5) The schema uses Zod refinements that are not exposed to the server.tool() registration, potentially causing schema visibility issues for clients; (6) File output handling is complex (absolute path validation, multi-image indexing) but underdocumented in parameter descriptions. The three tools are well-structured with proper enums, min/max constraints, and optional fields, but the overall tool system lacks maturity in error guidance and composition clarity.

• Document output schema for each tool. For base64 output, return {type: 'image', mimeType: 'image/png', b64_json: '...'}. For file output, return {type: 'file', path: '/path/to/image.png', mimeType: 'image/png'}. Include a total count if n > 1.
• Add error handling guidance to descriptions. Example: 'If prompt contains policy violations, try rephrasing. If file >25MB, compress first. If image generation times out, check OpenAI status.'
• Add tool annotations: mark all three tools with {"destructiveHint": true} since they generate content and write files. Consider idempotentHint analysis, image generation produces non-deterministic output, so likely idempotent=false.
• Rewrite tool descriptions to lead with user intent, not API parameters. Example for create-image: 'Generate a new image from a text description. Use this when you need an original image. For variations of an existing image, use varies-image. For edits to an existing image, use edit-image.'
• For the file_output parameter, expand the description to explicitly state: 'If n > 1 (multiple images), each file will be saved with an index suffix (e.g., /path/to/image_1.png, /path/to/image_2.png). If base64 output would exceed 1MB, output is automatically switched to file_output.'
• Expose Zod refinements to the server.tool() schema. Instead of bypassing refinements, use a custom schema builder that merges validation constraints into the JSON Schema. Or implement refinement checks early in the handler and return clear error messages ('If background=transparent, output_format must be png or webp').