photo-mcp demonstrates solid fundamentals with well-structured tool definitions, comprehensive schemas, and consistent use of tool annotations. All five tools follow a clear verb_noun naming convention (search_, get_), include detailed descriptions (150-250 chars each), and have proper JSON Schema definitions with type constraints and descriptions for all parameters. Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are uniformly applied. However, output schemas are not formally documented, responses are serialized to JSON strings without explicit field descriptions or reference documentation. Error handling is minimal (basic HTTP error throws with no recovery guidance). The server lacks pagination support despite tools returning lists (search_photos returns 5-20 results; get_collection_photos returns 10-30), and relationship-building between tools is weak (search_photos returns photo IDs, but no guidance on how to chain to get_photo or get_related_photos). Per-tool scores range from 68-76, averaging 72.

• Add formal output schemas to each tool. Document response structure in tool metadata: {"photos": [{"id": string, "url": string, "photographer": string, ...}], "total": number, "attribution": string (optional)}. Reference this in the description.
• Enhance error handling with recovery guidance. Replace 'Unsplash search failed: 404' with 'Photo "abc123" not found. Try search_photos(query="similar term") to find alternatives.' Include actionable next steps for each error type.
• Add offset/limit pagination for search_photos and get_collection_photos. Document in descriptions: 'Use offset (default: 0) and limit (default: 5, max: 20) to paginate large result sets. Response includes total count.'
• Add chaining hints to descriptions. E.g. search_photos: 'Returns photo IDs that can be passed to get_photo() for full details or get_related_photos() for visual matches.' Pattern:tool-chain.
• Validate ID formats before API calls. Add description text: 'ID format: 8-12 alphanumeric characters (e.g., "ElxBX6bsAgQ"). Invalid IDs return HTTP 404.' Consider Zod refinements to validate at schema level.
• Add rate-limit awareness. Document: 'Unsplash API has rate limits. If you receive a 429 error, wait before retrying.' Provide retry guidance in errors.
• Consider batch variants for future scale. If agents call get_related_photos many times, offer batch_get_photos(ids: string[]). Single-result variants are simpler but force N+1 patterns.
• Strip unnecessary response fields. Verify that generateAttribution and response structure only include fields LLMs need. Omit Unsplash internal metadata (e.g., user URLs not displayed to end-user).