PexelsMCP provides reasonable tool definitions with consistent naming (verb_noun pattern) and acceptable descriptions. All 9 tools have clear names starting with action verbs (search, download, get) and descriptions between 34 - 234 chars, within the acceptable range. Input schemas use Zod validation with types and enums. However, descriptions lack the specificity needed for optimal LLM reasoning, they rarely answer WHEN to use a tool vs alternatives, prerequisites, or what to do with the response. Output schemas are not formally documented; responses are inferred from code (content arrays with text fields). Parameter descriptions are present but generic, many lack concrete guidance on constraints, formats, or dependencies. Error handling is basic (try-catch with message echoing); no recovery guidance or categorization. No tool annotations (readOnlyHint, etc.) despite all tools being read-only. The server is competent but falls short of production-grade polish.
Tools (9)
downloadPhotoread onlyauthsource verified78/100
Download a photo by ID, with options for size/version selection
Output schema not formally documented. Responses are inferred from code inspection (content arrays with text/JSON fields). LLMs cannot plan downstream tool calls without explicit return type documentation.
Tool descriptions lack WHEN-to-use context and disambiguation from similar tools. E.g., searchPhotos vs searchVideos have identical description structure but serve different domains, descriptions should clarify that searchPhotos searches the photo library specifically. LLMs conflate similar-named tools.
Add formal output schema documentation to all tools. Document the shape of the response, field types, and required/optional fields. E.g., searchPhotos returns { total_results: number, photos: Array<{id, src, photographer, ...}>, rateLimit: {remaining, limit, reset} }.
Expand tool descriptions to clarify WHEN to use each tool vs alternatives. E.g., 'searchPhotos searches a full library of user-contributed photos; getCuratedPhotos retrieves Pexels-selected highlights. Use searchPhotos for specific queries; use getCuratedPhotos for discovery.' This prevents LLM confusion.
Add parameter constraint descriptions in the tool schema. E.g., for 'perPage', update description to 'Results per page (1 - 80; default 20). Larger values return more results per call but may exceed context windows.' For 'color', specify 'CSS color name (red, blue) or hex code (#ff0000). Optional; if provided, filters results.'
Remove example values from descriptions and move them to a separate examples field or parameter constraint. Replace 'Use descriptive keywords for relevant results (e.g., \'Thai hotel reception\')' with 'Use descriptive multi-word keywords (avoid single-word queries like \'hotel\' or \'car\')' and let the LLM adapt to context.
Implement error recovery guidance in catch blocks. Instead of 'Error searching photos: <message>', return 'Could not search photos for "<query>": <reason>. Verify the query is valid (e.g., \'sunset beach\', \'modern office\') and try again. If the issue persists, try getCuratedPhotos for browsing without a specific query.' This guides the agent toward resolution.
Score history
Overall score trend
↑ 18 points across a rubric change (v1 → v2)
52/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
52
2026-07-28+
v2
2026-03-09
F
34
-
v1
Retrieve popular videos from Pexels with filtering options
searchPhotosread onlyauthsource verified78/100
Search for photos using descriptive keywords and optional filters like orientation, size, and color
searchVideosread onlyauthsource verified77/100
Search for videos using keywords and optional filters
No error recovery guidance. Catch blocks return generic error messages (e.g., 'Error searching photos: [message]') without actionable guidance. If a photo is not found, the response should suggest search_photos as an alternative, not just fail.
No tool annotations. All 9 tools are read-only (no state modification), but readOnlyHint is not set. This prevents agents from optimizing decisions about retry safety and caching.
Parameter descriptions lack concrete constraints and examples of valid input. E.g., 'color' param says 'Desired photo color (e.g., 'red', 'blue', '#ff0000')' but does not specify: is it a CSS color name, hex code, or both? What format should an LLM use? This forces LLMs to guess or hallucinate values.
pagination parameters (page, perPage) lack min/max bounds in descriptions. Code enforces perPage max 80, but description does not state this. LLMs may pass invalid page numbers (0, negative) or perPage values > 80 without clear validation feedback.
Result limits not mentioned in tool descriptions. searchPhotos and other list/search tools return arrays, but descriptions do not state: how many results are returned by default? Is there a max? What does the total_results field mean? This forces LLMs to reason about pagination in the dark.
Tool descriptions in code include example values like 'Thai hotel reception', 'red sports car driving', 'en-US', 'es-ES', etc. LLMs often reuse example values literally in subsequent calls, causing failures when they pass 'Thai hotel reception' as a literal search query instead of adapting it to the current context.
searchPhotos
Add readOnlyHint: true to all 9 tool annotations. This signals to agents that these calls are safe to retry without side effects, enabling aggressive caching and retry strategies.
Document rate limiting in tool descriptions. Many tools include rate limit info in responses (remaining/limit/reset). Add a note: 'Each call is rate-limited. The response includes rate limit headers; if remaining hits 0, wait until reset before retrying. Consider caching results when possible.'
Add a Discovery/Help tool or section documenting the relationship between tools. E.g., 'searchPhotos for queries, getCuratedPhotos for discovery, getMyCollections to access saved collections, getCollectionMedia to browse within a collection.' This gives LLMs a mental model of the API shape.
For pagination, document the cursor/offset behavior. E.g., 'page: page number (1-indexed, default 1). Each page returns up to perPage results. Use page to paginate; responses include total_results to calculate max pages.'
Consider adding batch variants or multi-item support. E.g., downloadPhoto(ids: number[]) to download multiple photos in one call, reducing token overhead and latency for common agent patterns like 'download the top 3 photos from this search.'