Server has two tools with explicit schemas and descriptions. Both tools have comprehensive input schemas with proper types and constraints. However, descriptions lack depth and context for agentic selection. Schema completeness is good but output documentation is missing. Error handling is present but not well-integrated into tool descriptions. No tool annotations (readOnlyHint/destructiveHint) despite both tools having side effects. Parameter descriptions are present but could be more action-oriented for LLM reasoning.
Tool descriptions lack action context and LLM selection guidance. 'Resize and transform images' does not explain WHEN to use this vs alternatives, what the return format is, or what parameters are required vs optional.
No tool annotations (readOnlyHint/destructiveHint/idempotentHint) despite tools having side effects. resize_image writes files to disk (outputPath parameter); upload_image modifies cloud storage. LLMs need explicit marking of destructive operations.
Output schema not documented. Both tools process images but the response structure is not defined in the visible code. LLMs cannot plan downstream operations or validate results without knowing output fields.
resize_imageupload_image
HIGH
Recommendations
Add detailed tool descriptions (150-250 chars each) explaining: what the tool does, when to use it vs alternatives, what it returns, and any prerequisites. Example: 'Resize, rotate, apply filters (blur, sharpen, grayscale) and save images. Use this to prepare images for web (responsive sizing), apply visual effects, or normalize format. Returns the processed image URL (if outputPath set) or base64 data (if outputImage=true).'
Add tool annotations to both tools: mark resize_image with destructiveHint if outputPath overwrites files; mark upload_image with destructiveHint for overwrite=true scenarios. Use readOnlyHint for GET-like operations if added in future.
Document output schemas explicitly in the code. For resize_image: {'success': boolean, 'imagePath': string|null, 'base64': string|null, 'width': number, 'height': number}. For upload_image: {'success': boolean, 'uploadUrl': string, 'publicUrl': string|null, 'filename': string}.
Clarify mutual exclusivity in parameter descriptions. Add to both tools: 'Provide ONE of: imagePath (local file), imageUrl (remote URL), or base64Image (encoded data). If multiple are provided, imagePath takes precedence.'
Add per-parameter guidance for complex enums. For 'fit' parameter: 'Choose: cover (crop to fill both dimensions, default), contain (fit within bounds, letterbox with background color), fill (stretch to both), inside (scale down only if larger), outside (scale up only if smaller).'
Document upload_image service support in description. Example: 'Supports S3 (AWS), Google Cloud Storage (GCS), and Cloudflare R2. Configure via environment: UPLOAD_SERVICE=s3|gcs|cloudflare and service-specific credentials (AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS, CLOUDFLARE_BUCKET_NAME).'
Parameter naming inconsistency: resize_image accepts both imagePath, imageUrl, and base64Image (three input variants), while upload_image repeats the same pattern. This creates ambiguity, which parameter takes precedence if multiple are provided? No description clarifies mutual exclusivity or priority.
upload_image description lacks specificity about cloud storage service. 'Upload images to cloud storage services' is vague, which services are supported? What is the return format? Where is the uploaded image accessible? Dependencies on configuration are not documented.
resize_image parameters like 'position' (8 enum values) and 'fit' (5 enum values) have descriptions but lack examples of real-world usage. Descriptions state what the parameter does but not when an LLM should choose each option.
Error recovery guidance is missing. Neither tool description explains what to do if image processing fails, if cloud upload is rejected, or if file permissions prevent writing. No recovery actions documented.
resize_imageupload_image
Add error recovery actions to descriptions. Example for upload_image: 'If upload fails due to permissions, verify IAM credentials. If quota exceeded, check storage limits. If network timeout, retry with backoff. If filename collision and overwrite=false, the tool auto-appends a timestamp.'
Add idempotency guidance. For resize_image: 'Tool is idempotent when outputPath is set, re-running with same params produces identical output. When outputImage=true, base64 payload varies slightly due to compression, so hash-based deduplication may fail; use outputPath for deterministic caching.'
Document parameter constraints in descriptions using the format suggested in rubric: instead of listing constraints separately, embed them in parameter descriptions. Example for 'quality': 'Quality of output image (1-100; default 80; lower is smaller file size, higher is better fidelity).'
Add examples or use-case guidance to tool descriptions. For resize_image: 'Typical uses: generate responsive image thumbnails (width=300, height=300, fit=cover); optimize for web (quality=75, format=webp); apply effects (blur=2, grayscale=true).'
Expand parameter descriptions for non-obvious fields. For resize_image.background: 'Color when fit=contain adds letterboxing, or fit=cover extends beyond original bounds. Format: hex (#ffffff), rgb/rgba (rgb(255,0,0), rgba(0,0,0,0.5)), or CSS name (red, transparent).'
Document what happens with ambiguous inputs. For upload_image.folder: 'Service-specific behavior: S3 creates pseudo-folders as prefix (folder/filename); GCS and R2 treat as actual folder path. Nested paths (folder/subfolder) are supported; they will be created if the service allows.'
Add dependency hints in parameter descriptions. Example for resize_image: 'If you need aspect ratio preserved, set fit=contain or fit=inside rather than specifying both width and height exactly. If withoutEnlargement=true is set, the tool will skip resizing if input is already smaller than target dimensions.'
Document the relationship between outputImage and outputPath. Example: 'outputImage=true returns base64 data in response (useful for inline display, ~3-4x larger than file size); outputPath saves to disk (useful for file operations). Can set both to get both outcomes. base64 data is always URL-safe and does not include padding.'
Create separate parameter documentation for service-specific metadata. For upload_image: 'metadata parameter supports service-specific keys: S3 (cache-control, content-disposition); GCS (custom-metadata); R2 (none, but preserves custom headers). Unused keys are silently ignored per service.'
Add guidance on when to use base64Image vs imageUrl in upload_image. 'Use imagePath for files already on agent machine; imageUrl for images on web (tool will fetch); base64Image for dynamically generated or in-memory images from other tools. base64Image accepts data: URI format or raw base64.'