MCP server for searching Unsplash photos
Single tool with acceptable naming and moderate schema definition. Description is present but generic (194 chars, at baseline). Tool name 'search_photos' correctly starts with verb. Input schema is well-formed with types and reasonable defaults. However, parameter descriptions are minimal and some quality gaps exist: no error handling guidance, no output structure documented beyond docstring, color/orientation enums listed inline in description rather than as constrained schema, parameter relationships underdocumented, no pagination explicit in return type, and API key management via environment is correct but not mentioned in security context.
Search for Unsplash photos Args: query: Search keyword page: Page number (1-based) per_page: Results per page (1-30) order_by: Sort method (relevant or latest) color: Color filter (black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue) orientation: Orientation filter (landscape, portrait, squarish) Returns: List[UnsplashPhoto]: List of search results containing photo objects with the following properties: - id: Unique identifier for the photo - description: Optional text description of the photo - urls: Dictionary of available image URLs in different sizes - width: Original image width in pixels - height: Original image height in pixels
Enum constraints (color, orientation) documented as inline text in description rather than as JSON Schema enum fields. Invites hallucinated values.
Output schema documented in docstring but not in formal JSON Schema structure. LLMs cannot parse docstring schemas to plan downstream tool calls or extract fields reliably.
No pagination support visible in return type. Tool accepts page parameter but response does not indicate total_count, next_cursor, or result_count. Large result sets will blow context window without explicit limit.
No error handling guidance in description or docstring. When API fails (401, rate limit, network timeout), LLM receives raw exception with no recovery path. Should include: 'If API key invalid, error is ValueError about missing UNSPLASH_ACCESS_KEY. If rate limited (429), retry after 60s. If network timeout, retry with exponential backoff.'
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 63 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 47 | - | v1 |
Parameter 'order_by' accepts string with default 'relevant' but no enum constraint or validation. API docs suggest only 'relevant' or 'latest' are valid. Invalid values will fail silently at API layer.
per_page parameter accepts range 1-30 but schema uses union type (integer|string) without explicit min/max constraints. Type coercion at runtime (try/except int()) is fragile; LLM could pass '100' as string and it coerces silently to int, then gets capped at 30 without feedback.