Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
This server has significant gaps in definition quality. Of 2 tools: health_check has minimal schema (empty input object) and adequate description; generate_image_imagen3 has a comprehensive parameter schema but lacks output schema documentation and has no guidance on error handling or recovery. Descriptions are present but inconsistent in depth. No tool annotations (readOnlyHint, destructiveHint) are declared despite clear side-effect distinctions. Parameters are well-defined for imagen3 but lack enum constraints for mutually exclusive options (e.g., aspect_ratio should enumerate valid ratios; model_version should be an enum). No pagination or result limits are documented despite image generation potentially returning multiple images. Error handling is absent, no guidance on what happens when API calls fail, rate limits are hit, or Supabase uploads fail.
Output schema not documented. generate_image_imagen3 description claims to 'Generate images' but does not specify what the response contains (image URLs, base64 data, Supabase paths, metadata structure, array format for multiple images). LLMs cannot plan downstream calls without knowing output structure.
Parameters lack enum constraints and format validation. aspect_ratio, image_size, output_format, and model_version accept free-form strings. No enum declarations. Documentation in code (server.py) references valid options (aspect_ratio examples: '1:1', '9:16', '4:5'; image_size: '1K' or '2K'; output_format: 'png' or 'jpeg'; model_version: 'imagen-4.0' or 'imagen-3.0') but these are not exposed in schema. LLMs will hallucinate invalid values.
No error handling or recovery guidance. If Google API fails, Supabase upload fails, or rate limits are hit, the tool returns raw exception details with no guidance to the LLM on retryability, user action, or alternatives. No structured error response with actionable next steps.
Recommendations
Add comprehensive output schema documentation for generate_image_imagen3. Specify: response structure (object with fields like 'images' array, 'metadata', 'supabase_urls' if upload succeeded); per-image structure (id, url, base64, size, format, generation_metadata); error fields if applicable. Example: {"images": [{"id": "str", "url": "str", "size_bytes": int, "format": "str"}], "total_generated": int, "supabase_upload_status": {"success": bool, "public_urls": [str], "error": str?}}
Convert free-form string parameters to enums in schema. For aspect_ratio: enum=["1:1", "4:5", "9:16", "16:9", "3:2", "2:3"]. For image_size: enum=["1K", "2K"]. For output_format: enum=["png", "jpeg"]. For model_version: enum=["imagen-3.0", "imagen-4.0"]. Update descriptions to reference the enum list.
Add tool annotations to schema. health_check: add readOnlyHint=true. generate_image_imagen3: add destructiveHint=true (API call has cost) and note that idempotentHint=false (same parameters may return different images).
Implement structured error responses with recovery guidance. Examples: if Google API fails with rate limit, return {"error": "rate_limited", "retry_after_seconds": 60, "guidance": "Wait 60 seconds and retry."}. If Supabase upload fails, return {"error": "upload_failed", "images_generated": true, "base64_data": [...], "guidance": "Images generated but not persisted. Check Supabase credentials."}.
Document output and constraints for health_check. Add description to output schema specifying fields: {"status": "healthy|degraded|unhealthy", "checks": {"google_api": bool, "supabase": bool}, "uptime_seconds": int}.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
No tool annotations despite clear side-effect distinctions. health_check is READ_ONLY but no readOnlyHint declared. generate_image_imagen3 is destructive/stateful (writes to cloud storage) and triggers external API calls with cost implications, no destructiveHint or side-effect warning. Agents cannot determine safety of retry.
health_check input schema is empty ({}). While minimal tools can have zero parameters, the schema lacks any documentation of what it returns (e.g., status object structure, fields like 'google_api_ready', 'supabase_ready', 'uptime'). Without documented output, LLMs cannot use the result.
Supabase upload feature exposed as parameter (upload_to_supabase) with default=true. If Supabase is misconfigured or credentials absent, tool silently degrades (code logs warning but returns image anyway). No explicit error or notification to agent. LLM assumes upload succeeded when it may have failed.
No parameter relationship documentation. number_of_images and aspect_ratio are independent, but if the agent requests 10 images at 2K resolution in PNG format, cost and time implications are not surfaced. No guidance on rate limits, quota, or practical max values.
Naming lacks specificity. 'generate_image_imagen3' names the model version in the tool name, but model_version is also a parameter. This is redundant and confusing, if model_version can be 'imagen-3.0' or 'imagen-4.0', the tool name should be generic like 'generate_image' and model choice should be parameter-driven. Alternatively, split into generate_image_imagen3 and generate_image_imagen4.
generate_image_imagen3
Add parameter constraints (min/max/pattern) for generate_image_imagen3. number_of_images: minimum=1, maximum=10 (enforce practical limit to prevent runaway costs). Negative_prompt: maxLength=1000. Prompt: minLength=1, maxLength=2000. Add these to parameter descriptions and schema.
Clarify Supabase upload behavior. If upload_to_supabase=true but credentials are missing, should the tool: (A) fail hard, (B) succeed with base64 fallback and warn, or (C) skip upload silently? Choose one and document explicitly in description. Recommend option (A) for clarity unless fallback is intentional.
Rename tool to remove version specificity or split by model. Option 1: Rename to 'generate_image' and use model_version parameter exclusively. Option 2: Keep 'generate_image_imagen3' but remove model_version parameter (one tool per model). Recommend Option 1 for flexibility.
Add rate limit documentation. Specify: calls per minute allowed, images per month quota, cost per image, timeout duration. Include in tool description: 'Note: Google Imagen API enforces rate limits. Requests exceeding X calls/min will be rejected. Cost: $Y per image.'
Document Supabase integration explicitly. Add parameter description: 'If upload_to_supabase=true, generated images are stored in Supabase Storage bucket (SUPABASE_STORAGE_BUCKET env var). Requires SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY to be set. If credentials missing, upload is skipped and images returned as base64 only.'
Add example output to tool descriptions (in text, not in schema). E.g., 'Returns object: {"images": [{"id": "img_abc123", "url": "https://...", "base64": "iVBORw0KG..."}], "metadata": {"model": "imagen-4.0", "cost_usd": 0.05}}'.