Sleep Blocker MCP has foundational tool structure but significant quality gaps. Tool names follow verb conventions (start_, stop_, get_, list_, set_) which is good. However, descriptions lack depth and context for LLM decision-making. Parameter descriptions are minimal or absent. Output schemas are not documented. The server uses stateful global variables (active_process, start_time, duration_seconds) which violates stateless request handling principles. Error handling exists but lacks recovery guidance. No parameter validation beyond enums. Tool composition is reasonable (5 single-purpose tools), but the set_duration_preset tool is problematic, it returns duration_minutes but doesn't actually start prevention, making its utility unclear. The code shows the tool implementation details are visible, so we can score based on actual definitions rather than inference.
Tools (5)
get_sleep_statusread onlysource verified67/100
Get current sleep prevention status and remaining time
list_sleep_modesread onlysource verified70/100
List all available sleep prevention modes with descriptions
set_duration_presetread onlysource verified63/100
Set duration using preset values (30min, 1hr, 2hr, 4hr, indefinite)
start_sleep_preventionwritesource verified70/100
Start preventing system sleep with specified mode and duration
Output schemas completely undocumented. Tool responses return structured objects (process_id, start_time, elapsed_seconds, remaining_time, modes array, etc.) but none of these fields are documented in schema definitions. LLMs cannot predict response structure or plan chaining.
Descriptions lack LLM decision context. Most descriptions (stop_sleep_prevention, get_sleep_status, list_sleep_modes) are bare action statements without 'when to use this' guidance. LLMs cannot distinguish between start_sleep_prevention in 'display' mode vs 'idle' mode without deeper description context.
set_duration_preset tool has unclear purpose and breaks composition. It converts presets to minutes but doesn't apply them, LLMs must somehow know to pass the returned duration_minutes to start_sleep_prevention. The tool name implies state change ('set') but performs no action. This violates single-responsibility and composability patterns.
Recommendations
Add explicit output schemas for all tools. Example for start_sleep_prevention: {"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"mode":{"type":"string"},"duration_minutes":{"type":"integer","nullable":true},"process_id":{"type":"integer","nullable":true},"start_time":{"type":"string","format":"date-time"}}}
Expand all tool descriptions to 80-150 chars. Include 'when to use' context. Example: 'start_sleep_prevention: Prevent macOS from sleeping for a specified duration and mode. Use this when you need the system to stay awake (e.g., during a presentation or long-running task). Returns the process ID and start time for tracking.'
Add detailed parameter descriptions to mode enum. Current schema only lists values; add descriptions in the param text: 'mode (string, enum): Sleep prevention mode. display = Keep screen on while allowing system sleep; idle = Keep system awake but allow display to sleep; disk = Keep hard drives spinning; ac = Prevent sleep only when connected to power; all = Keep everything awake.'
Consolidate set_duration_preset into start_sleep_prevention. Instead of returning duration_minutes, support a duration parameter like 'duration_preset' (enum) alongside duration_minutes. Example: start_sleep_prevention(mode='idle', duration_preset='30min') → calls caffeinate directly with -t 1800. This eliminates the confusing separate tool and reduces LLM reasoning cycles.
Add error recovery guidance. Example: When no active process exists, return: {"success":false, "message":"No active sleep prevention. To start, call start_sleep_prevention(mode='idle') or choose a mode via list_sleep_modes()."}
Parameter descriptions missing or minimal. duration_minutes parameter says only 'Duration in minutes. Omit for indefinite.' but doesn't state the valid range, precision, or what 'indefinite' means exactly. The mode parameter description is in the enum labels only, not in the param description text.
Stateful global variables (active_process, start_time, duration_seconds) violate stateless request handling. MCP protocol (current spec 2026-07-28) requires each request to be self-contained. If the server restarts or handles concurrent clients, state is lost. This also makes STDIO transport (single-threaded) dangerous for concurrent clients.
Error handling lacks recovery guidance. When stop_sleep_prevention returns 'No active sleep prevention to stop', the LLM has no actionable next step. Should suggest: 'To start sleep prevention, call start_sleep_prevention()' or 'Call get_sleep_status() first to check if prevention is active.'
No input validation or constraint documentation. Mode enum is declared but no description explains what each mode does (display = 'Keep screen on', idle = 'Keep system awake', disk = 'Keep drives spinning', ac = 'On AC power only', all = 'Everything'). LLMs must infer or call list_sleep_modes separately.
No documentation of tool semantics. Is start_sleep_prevention idempotent? (Code shows it cleans up existing process, so yes, but description doesn't state this.) Are calls to stop_sleep_prevention safe to retry? This metadata is critical for agent planning.
start_sleep_preventionstop_sleep_prevention
Replace 'remaining_time' field with 'remaining_seconds' only (or keep both but note they are equivalent). Document the output schema explicitly: 'remaining_time is a human-readable duration string; remaining_seconds is an integer. Choose one for your use case.'
Add tool annotation hints (readOnlyHint/destructiveHint/idempotentHint) if protocol supports. start_sleep_prevention and stop_sleep_prevention are destructive (modify system state); get_sleep_status and list_sleep_modes are read-only; start_sleep_prevention is idempotent (repeated calls just restart the process).
Document the macOS-only platform requirement. All tools depend on the caffeinate command, which is macOS-specific. Add a description prefix: '[macOS only] Prevent system sleep...'
Add a 'current_mode' field to get_sleep_status output schema. When active, return the mode that was started (e.g., 'display', 'idle'). This enables agents to make informed decisions about stopping or restarting with a different mode.
Validate duration_minutes input. Add a description: 'duration_minutes (integer, 1-1440): Duration in minutes. Must be between 1 and 1440 (24 hours). Omit or pass null for indefinite prevention.' Then validate and reject values outside this range with a clear error: 'duration_minutes must be 1-1440 minutes or null for indefinite.'
Remove stateful global variables. Store the active process ID and metadata in a server-local structure keyed by request/client ID if STDIO must support multiple agents, or document that only one agent may use this server at a time. Better: migrate to HTTP transport with per-request context.