Five tools with clear verb-noun naming (status, list_folder, search, download, read_text) and documented descriptions (avg 95 chars). All tools have input schemas with typed parameters and descriptions. However, output schemas are not explicitly documented in the source, responses are inferred from code patterns (ok() wrapper, item.to_dict()). Parameter descriptions are present but minimal (avg 45 chars). Error handling returns structured dicts with 'ok', 'code', 'error' fields, but recovery guidance is sparse. No tool annotations (readOnlyHint, destructiveHint). Risk classification is present in metadata but not in tool definitions themselves.

• Document output schemas for all tools. E.g., status returns {ok: bool, drive_reachable: bool, ...}; search returns {ok: bool, query: str, count: int, truncated: bool, visited: int, items: [{name, type, modified, ...}]}. Use JSON Schema or explicit field descriptions.
• Expand parameter descriptions to 60 - 120 chars with format/constraint details. E.g., 'path: Folder path in iCloud Drive (e.g., "/Documents/Reports"). Empty string means root. Max depth 10 levels.' Avoid example values; use constraints instead.
• Add tool annotations: @mcp.tool(readOnlyHint=True) for status, list_folder, search, read_text; @mcp.tool(destructiveHint=True) for download. This signals retry safety and side-effect scope to LLMs.
• Enhance error responses with recovery guidance. E.g., if code='NEED_LOGIN', append 'Next step: Run `icloud-docs-mcp login` in a terminal to authenticate.' If code='INVALID_PATH', return available paths: 'Available folders: /Documents, /Photos, /Desktop'.
• Add pagination to search(). Accept offset/limit, return total_count and next_offset. If truncated=true, LLM can call search(..., offset=30) to fetch more results without re-querying.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry