The server has 5 well-defined tools with solid naming conventions and reasonably complete schemas. All tools start with action verbs (search_, extract_, get_, resolve_) following pattern:tool guidance. Descriptions are present and contextual, averaging ~100-120 chars (within the 10-1024 char band). Input schemas use Zod with proper type constraints including enums, minLength, min/max bounds. However, output schemas are undocumented, responses are JSON-stringified but the structure of that JSON (fields, types, nesting) is never declared. Error handling is minimal: no recovery guidance, no actionable error messages, no categorization of retryable vs fatal errors. Parameter dependencies (e.g., orientation applies to search but not extraction) are not explicitly documented. The batch variant (search_images_batch) is a good composition pattern, but there is no guidance on when to use it vs search_images. Overall: solid foundation with gaps in output documentation and error guidance.

• Document the output schema for each tool. For search_images, explicitly state: 'Returns an object with keys url, source, photographer, width, height, tags (array). Example: {url: string, source: 'Pexels'|'Unsplash', photographer: string, width: number, height: number, tags: [string]}.' This enables LLMs to extract and chain results.
• Add error recovery hints to tool descriptions. E.g., search_images: 'If the API returns a 429 rate limit error, wait 60 seconds before retrying. If 401 (invalid key), check your PEXELS_API_KEY environment variable.' This guides the LLM's next action.
• Clarify get_best_image ranking logic in the description. Replace 'Return a single best image' with 'Return the highest-rated image by download count / views / relevance score for the query. Use this when you need exactly one recommendation; for multiple options, use search_images.'
• Add a dependency hint to extract_image_query. Description should note: 'Use this tool when you have free-form text (e.g., a blog post snippet) and want to extract keywords for search_images. If you already have a clear search term, call search_images directly.'
• In search_images_batch, clarify when to use it vs looping. E.g., 'Searches 2 - 10 queries in parallel, reducing latency. For a single query, use search_images instead. Returns results keyed by query string.'
• Validate API keys early and return a clear error: 'Invalid Pexels API key. Set PEXELS_API_KEY environment variable. Get a free key at https://www.pexels.com/api/' instead of letting the 401 propagate unadorned.