Loading ToolBench
PyAutoGUI-MCP has only 1 tool (pyautogui_hotkey) with a minimal schema and generic description. The tool definition is visible in app.py with parameter type hints inferred from _NAME_TYPE_HINTS dictionary and _infer_param_type logic. However, the schema lacks formal descriptions for parameters, the tool description is extremely brief (12 chars), and there is no documented output schema. The tool is a WRITE-class operation that directly manipulates the system (pressing keys), but error handling is absent, no guidance on what happens if a key is invalid, if the operation fails, or how to recover. The server is STDIO-only, which caps protocol readiness at 50 regardless of other factors. Input schema is present but incomplete: 'keys' parameter has a list type but no item type specification, and 'interval' has a default but no range constraints or explanation of units (seconds vs milliseconds is ambiguous).
Press a key chord, e.g. keys=['ctrl','c']
Tool description is only 12 characters ('Press a key chord, e.g. keys=[ctrl,c]'), far below the 10 - 1024 char guideline baseline and provides almost no context for LLM selection. Does not state WHAT happens (keys are pressed), WHEN to use it (keyboard input, hotkey triggers), or WHAT it returns (success? pressed keys list?). No guidance on destructive intent or side effects.
Parameter 'keys' has no description. Schema declares it as list type but does not specify item type (should be list of strings). LLMs cannot infer that 'keys' expects ['ctrl', 'c'] vs [1, 2] or mixed types. Missing description for 'interval': units are ambiguous (seconds? milliseconds?), range is unconstrained (can agent pass negative or 1e6?), and purpose is unclear in isolation.
No output schema documented. Tool returns result of _normalise(result), which could be None, a normalized object, or an image, but the tool description does not state this. LLMs cannot plan downstream calls or validate success without knowing return type. Baseline: 100% of A+ tools have documented return types.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 35 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 21 | - | v1 |
No error handling or recovery guidance. Tool is a WRITE operation that directly manipulates the host OS (presses keys globally). If an invalid key is passed, if X11 display is unavailable, or if FAILSAFE is triggered, the error response is silent to the LLM. No guidance on: 'Invalid key. Allowed keys: ctrl, shift, alt, …' or 'Keyboard unavailable, check DISPLAY or OS permissions.' Pattern: recovery-guide.
Tool name 'pyautogui_hotkey' is module-centric, not action-centric. Verb is missing, should be 'press_keys' or 'send_hotkey' to signal the action. Current name reads like a library function, not an agent tool intent. LLM must read the description to understand the action, but description is too short to clarify.
WRITE operation with no confirmation or dry-run option. Agents make mistakes, pressing Ctrl+D or Ctrl+Z unintentionally can corrupt user data or close applications. Tool should either require confirmation before execution or offer a dry-run mode. Pattern: confirmation-request.
No range or enum constraints on 'interval' parameter. Unbounded float allows agent to pass negative intervals, 1e6 second pauses, or NaN values. LLMs lack external constraints and will pass invalid values. Should declare: 'interval: float, 0.0 - 10.0 seconds, controls pause between key presses.'