photomind-mcp demonstrates solid naming conventions (verb_noun pattern: sync_library, search_by_date, get_photo_metadata) and comprehensive parameter schemas with types and descriptions. Tool descriptions are detailed and explain prerequisites (e.g., 'Requires sync_library() to have been run'). However, output schemas are not formally documented, responses are inferred from code but not declared in tool definitions. Error handling returns structured objects but lacks actionable recovery guidance (e.g., 'Run sync_library() first' is present in get_photo_metadata but inconsistent across tools). Parameter descriptions are strong (72-char baseline met), but some tools lack enum constraints for categorical inputs (e.g., group_by in organise_photos accepts 'year_month' or 'year' but is a free-form string, not an enum). No tool annotations (readOnlyHint, destructiveHint) despite clear risk classifications in metadata.
Find groups of near-duplicate photos using CLIP semantic similarity. Compares all embedded photos pairwise and returns groups where any pair has cosine similarity ≥ threshold. Uses union-find so transitive duplicates are in the same group. Args: threshold: Cosine similarity cutoff (0–1). Default 0.98 is strict; lower to 0.90 to surface more near-duplicates.
Score photos by sharpness and return those that appear blurry or low-quality. Loads each photo's image file and computes a sharpness score using edge-pixel variance. Photos below blur_threshold are considered poor quality. Args: blur_threshold: Sharpness cutoff (default 100.0). Typical range: ~50 (very blurry) to ~500+ (sharp). Lower to catch only the blurriest. update_db: Persist quality_score to the database (default True). limit: Max poor-quality photos to return (default 50).
Return the full metadata record for a single photo by its UUID. Args: photo_id: The Photos.app UUID (e.g. from search results).
Analyse library structure and suggest a folder organisation. Read-only: does NOT move or modify any files. Returns a suggested folder hierarchy with photo counts and up to 3 sample UUIDs per folder. Args: group_by: Grouping strategy — 'year_month' (YYYY/MM, default) or 'year'.
Output schemas not formally documented. Tool descriptions explain what is returned (e.g., 'Returns a summary with total, indexed, skipped, errors, duration_seconds') but response structures are not declared in tool definitions. LLMs cannot plan downstream calls without knowing exact field names and types.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Tools are marked with Risk metadata (READ_ONLY, WRITE) in the server metadata but not exposed via MCP tool annotations. Agents cannot determine which tools are safe to retry or have side effects.
Categorical parameters lack enum constraints. 'group_by' in organise_photos accepts 'year_month' or 'year' but is defined as a free-form string. LLMs may hallucinate invalid values like 'month' or 'year_week'. Should use JSON Schema enum.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 61 | <=2025-11-25 | v2 |
Find photos taken within a date range. Args: start_date: ISO-8601 date string, e.g. '2023-01-01'. end_date: ISO-8601 date string, e.g. '2023-12-31'. limit: Maximum results (default 50, max 500).
Find photos taken near a GPS coordinate. Args: latitude: Decimal degrees, e.g. 1.3521 (Singapore). longitude: Decimal degrees, e.g. 103.8198. radius_km: Search radius in kilometres (default 5.0). limit: Maximum results (default 50).
Find photos by metadata: keywords, camera model, or tagged people. At least one filter must be provided. All filters combine with AND logic. Args: keywords: Keywords to filter by (AND-combined). camera_model: Partial camera model name, e.g. 'iPhone 15' (case-insensitive). persons: Person names from Photos.app face tags (AND-combined). limit: Maximum results (default 50).
Search photos using natural language via CLIP semantic similarity. Converts the query to a vision-language embedding and finds the most visually/semantically similar photos in the library. Requires sync_library() to have been run with embedding generation enabled, and sqlite-vec to be available. Args: query: Natural language description, e.g. 'sunset at the beach', 'food photo', 'people laughing outdoors'. limit: Maximum results to return (default 10).
Index all photos from Photos.app into the local SQLite database. Must be called at least once before search tools return results. Safe to re-run; existing records are updated in place. Returns a summary with total, indexed, skipped, errors, duration_seconds.
Error handling inconsistent. get_photo_metadata returns 'Run sync_library() first' but search_by_date returns generic 'Search failed: {exc}'. Agents need consistent, actionable error guidance across all tools.
Result limits not enforced consistently. search_by_date, search_by_location, search_by_metadata cap at 500; search_photos caps at 100; find_duplicates has no limit. Unbounded results risk context window exhaustion. Descriptions should state limits clearly.