The server provides 27 tools with explicit input schemas and descriptions. However, the definitions suffer from several significant issues: (1) Many tools lack meaningful context about their purpose and consequences, descriptions are terse and don't explain WHEN to use them or WHAT side effects occur. (2) Tool naming lacks clarity in distinguishing related operations, e.g., file_put, file_put_preview, file_put_confirm, and file_upload_preview, file_upload_confirm are confusing and could be consolidated. (3) Parameter descriptions are often generic or missing context about valid ranges and relationships. (4) Output schemas are not documented, the source code does not show what these tools return, making it impossible for LLMs to plan downstream chains. (5) Error handling is not evident in the definitions, no guidance on retryability, recovery steps, or actionable error messages. The server does follow some good patterns: enum constraints for direction and action parameters, numeric bounds for coordinates and sizes, and path validation. Overall, definitions are mechanically complete but lack the depth and clarity needed for confident LLM usage.
Connect to the vphone bridge. Establishes a connection to the bridge daemon and performs handshake. Returns bridge capabilities and protocol version. The connection uses authentication via VPHONE_API_TOKEN environment variable if set. The token is sent as a Bearer token in the handshake.
Disconnect from the vphone bridge. Closes the UDS connection and transitions to DISCONNECTED state. All in-flight requests are cancelled with CONNECTION_LOST error.
Press and hold a HID button. Sends a HID button down event. The button remains pressed until vphone_hid_up is called with the same page and usage. Args: page: HID usage page (e.g., 0x0C for Consumer page) usage: HID usage code within the page Returns: HIDKeyOutput with success status
Press and release a HID button. Sends a HID button press and release event. This is a complete press cycle (down then up) in a single operation. Args: page: HID usage page (e.g., 0x0C for Consumer page) usage: HID usage code within the page Returns: HIDPressOutput with success status
Release a held HID button. Sends a HID button up event. Releases a button that was previously pressed with vphone_hid_down. Args: page: HID usage page (e.g., 0x0C for Consumer page) usage: HID usage code within the page Returns: HIDKeyOutput with success status
Output schemas not documented. The source code does not show what any tool returns, forcing LLMs to guess at response structure and preventing accurate chaining and field extraction.
Confusing multi-step tool names and workflow. Tools like file_put_preview, file_put_confirm, file_upload_preview, file_upload_confirm create ambiguity about when to use which. The distinction between 'file_put' and 'file_upload' workflows is not explained. Descriptions lack WHEN to use each pattern.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 9 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 43 | - | v1 |
Press the Home button. Simulates pressing the home button on the device. Equivalent to vphone_hid_press(HIDPage.CONSUMER, HIDUsage.HOME).
Ping the bridge to check connectivity. Sends a ping message and measures round-trip latency. Requires an active connection. Raises: NotConnectedError: If not connected to bridge ConnectionUnavailableError: If bridge is reconnecting
Press the Power button. Simulates pressing the power button on the device. Short press: sleep/wake. Long press: power dialog. Equivalent to vphone_hid_press(HIDPage.CONSUMER, HIDUsage.POWER).
Get the current connection status. Returns the current state of the bridge connection without sending any messages to the bridge. This queries the internal state machine. States: - disconnected: No active connection - connecting: Connection in progress - connected: Active connection ready for requests - reconnecting: Connection lost, attempting recovery - error: Connection failed
Get the bridge version information. Returns protocol version and supported features. Requires an active connection. Raises: NotConnectedError: If not connected to bridge ConnectionUnavailableError: If bridge is reconnecting
Press the Volume Down button. Simulates pressing the volume down button on the device. Equivalent to vphone_hid_press(HIDPage.CONSUMER, HIDUsage.VOLUME_DOWN).
Press the Volume Up button. Simulates pressing the volume up button on the device. Equivalent to vphone_hid_press(HIDPage.CONSUMER, HIDUsage.VOLUME_UP).
Terse descriptions that do not explain purpose, consequences, or alternatives. Examples: 'Establish connection to vphone bridge' (no explanation of what 'connection' means or what it enables), 'Query current connection status' (does not clarify what state values mean), 'Home button press convenience tool' (no context on when to use vs. hid_press). LLMs cannot determine when to select these tools.
Missing documentation of side effects and irreversibility. Tools like power, hid_press, set_location, file_delete_confirm modify device state but descriptions do not warn agents about consequences or whether calls are idempotent. No guidance on retry safety.
No error handling guidance in tool descriptions. No mention of what errors are possible, whether they are retryable, or what the LLM should do next. For example, file_get could fail with 'file not found' or 'permission denied', the description does not say what to expect or how to recover.
Unclear parameter relationships and dependencies. The preview/confirm workflow (file_put_preview → file_put_confirm) requires a preview_token, but the preview tool descriptions do not explain that the token must be captured and reused. Agents may not understand the dependency.
Ambiguous tool naming for HID input tools. 'hid_press' and 'hid_key' both control keyboard/button input but differ in behavior (press = down+up in one call vs. key = explicit down or up). Naming does not reflect this distinction. LLMs will conflate them.
Parameter descriptions lack actionable constraints. For example, file_list 'path' parameter says '1-4096 characters' but does not say if paths must be absolute, relative, or if '~' is expanded. file_get 'encoding' says 'base64, hex, metadata_only, default base64' but does not explain what metadata_only returns or when to use each encoding.
No documentation of pagination or result limits. file_list supports 'recursive' but does not specify a cap on results returned, whether there is a default limit, or how to handle deep directory trees. This risks context window exhaustion.
Permission and authentication not addressed in tool descriptions. Tools like file_get, file_put, and dev_mode modify device state but do not clarify what permissions are required, what the user/agent authorization model is, or how failures are signaled.