vdroid-scripter drives Android devices with CV-located steps composed from a human-curated library. Provides tools for device control, automation scripts, library management, and session handling via MCP protocol.
vdroid-scripter has 13 well-named tools with clear verb_noun naming (ping, list_devices, queue_steps, wait_for_session, etc.). All tools have descriptions ranging from 85 - 280 characters, well within the 10-1024 baseline. Most parameters include types and descriptions. The tool set is cohesive: read-only tools (scan, get_library, get_routes) are separate from write tools (queue_steps, save_route, record_action). Complex schemas (e.g., queue_steps landmarks chain with enum types for 'image'/'text'/'yolo') are well-structured. However, there are gaps: (1) output schemas are not documented in the provided source, we cannot verify what scan(), get_library(), or get_routes() return, (2) some parameter descriptions lack format constraints (e.g., 'locale' in landmarks is noted as 'Tesseract language code' but no enum of valid codes is shown), (3) error handling guidance is implicit (e.g., 'Name step that failed' for wait_for_session) but not formalized into recovery patterns, and (4) the ping tool's purpose ("Starts the vdroid server when needed") suggests implicit server state management, which could be documented more explicitly. The tool descriptions are appropriately detailed and actionable, e.g., queue_steps includes guidance on batching and default delay/timeout behavior. Naming is strong across all 13 tools.
Lists available library images (template crops) and recorded actions (gestures). Call only when image targets or recorded gestures are needed. Library names carry context: <app>_<screen>_<what>[_variant].
Retrieves a saved route by name, including its prompt and all steps. Used to extend or modify routes before saving.
Lists saved automation flows (routes). Each route is a named sequence of steps that ran successfully.
Gets current session status without waiting. Primarily used for debugging. Prefer wait_for_session after queue_steps.
Lists available Android devices with their serials and properties. Required to get a device serial for subsequent operations.
Starts the vdroid server when needed and waits for it to be ready. Must be called first before other operations.
Output schemas are not documented. The source code shows tool descriptions but no explicit return types for read-only tools (get_library, scan, get_routes, get_session_status). Without documented return schemas, LLMs cannot infer what fields are available for downstream chaining or extraction.
Parameter enum constraints are incomplete. The 'locale' parameter in queue_steps landmarks is described as 'Tesseract language code' but no enum of valid codes (eng, fra, deu, etc.) is provided. This invites LLM hallucination of invalid locale strings.
Error responses lack recovery guidance. wait_for_session returns 'error status naming the failed step' but the description does not explain what the LLM should do next (retry from start_id, inspect logs, call scan for diagnostics). Error classification (retryable vs. fatal) is not explicit.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 61 | <=2025-11-25 | v2 |
Queues a sequence of steps for execution on the device. Steps execute sequentially. Each step applies an event (tap, long_tap, swipe, type_text) to a chain of landmarks (image, text, or yolo). Never queue one step at a time - batch the whole sequence into a single call.
Records a gesture from the device as a library action. Device listens for 5 seconds from call time. Blocks until window ends. Call only when user explicitly asks to record - never on your own initiative. 'nothing recorded' means no touch happened.
Executes a saved route. Accepts optional start_id to run from a specific step (use when recovering from failure or running remainder after fix). Step ids are 1-based position numbers.
Saves a flow as a route with a name, user's dictation as prompt, and the exact steps that succeeded. Duplicate names overwrite. To extend a route: get_route, append new steps, call save_route with full list.
Observes the screen by scanning for specified library images. Only way to see what is on screen. Call when a step failed, for conditional logic, or when user explicitly asks what is visible. Never scan habitually between steps.
Shuts down the entire vdroid server process. Every device session closes. Only call when user explicitly asks to stop or restart. Next tool call starts it again on demand.
Waits for queued steps to complete. Returns 'idle' when all steps succeeded, or error status naming the failed step. Call once after queue_steps - never poll between steps.
Implicit server state coupling. The ping tool description states it 'Starts the vdroid server when needed' and must be called first. This introduces hidden dependency and stateful initialization. The MCP protocol should be stateless per request, server readiness should be transparent or negotiated via capabilities.
Parameter type constraints underspecified. The 'delay' and 'timeout' numeric parameters in queue_steps lack explicit min/max bounds. No guidance on whether delay can be 0, or maximum timeout allowed. Unbounded numbers can cause LLM to pass unreasonable values (e.g., 1-hour timeout).