A virtual screen on Hyprland for AI agents, providing graphical interaction capabilities without touching the human's desktop
hyprcage demonstrates solid tool design with consistent naming (verb_noun pattern), comprehensive parameter descriptions, and clear risk classifications. All 18 tools have descriptions (avg 85 chars) and input schemas with typed parameters. However, output schemas are undocumented, LLMs cannot predict response structure for downstream chaining. Error handling is minimal; tools lack recovery guidance. Parameter descriptions are good but could be more prescriptive about constraints (e.g., regex patterns for screen names, pixel bounds). The batch tool is well-designed for composition. Missing: documented return types, actionable error messages, and per-tool examples of success/failure cases.
Ask a window to close
Run an application inside a screen
Execute multiple actions in sequence
Click at screen coordinates
Double-click at screen coordinates
Drag from one point to another
Press key combinations
Open or close the human's mirror window for a screen
Output schemas undocumented. Tools return structured data (e.g., screenshot returns image + geometry JSON, windows returns window list) but LLMs cannot predict response fields for chaining. Documented return types are required for tool composition.
Error handling lacks recovery guidance. Tools do not document what errors are retryable, what user actions are needed, or what to try next. E.g., 'screen not found' should suggest 'call screen_list() to see available screens'.
Parameter constraints not fully specified. Screen name pattern '[a-z0-9-]{1,32}' is documented in description but should be in schema as regex. Pixel bounds (max 2000) are mentioned but not enforced via schema minmax. Settle_ms and timeout ranges lack explicit bounds.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 61 | 2026-07-28+ | v2 |
Move the pointer
Create an agent screen with optional name and size
Close a screen
List screens
Capture a screen to PNG or JPEG
Scroll at screen coordinates
Install cage (asks for your password)
Type Unicode text
Wait for time, image stability or a window title
List the windows of a screen
Tool annotations missing. Tools declare Risk (WRITE, DESTRUCTIVE, READ_ONLY) in metadata but MCP schema does not expose readOnlyHint, destructiveHint, or idempotentHint. LLMs cannot see risk classification without explicit schema annotations.
setup tool lacks security context. Asks for password but does not document how credentials are handled, whether they are logged, or what permissions are required. Sensitive operations need explicit security guidance.