sandbox_key

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does add some real behavioral signal beyond the schema: keys are delivered to the sandbox's keyboard, and "super" triggers the desktop's application search, which reveals the effect lands on the active desktop session. It omits key gaps, though — whether the sandbox must be running, which window receives focus, and whether a press can have destructive side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action is front-loaded in sentence one, with the format rules, examples, and valid value lists following in a logical order. The long key-name enumeration is verbose but earns its place by substituting for a missing schema enum.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be described, and the low-complexity two-parameter shape means the description covers most of what an agent needs. However, sandbox_id receives no explanation and the description never states the operational precondition (an active/running sandbox with a focused window) that determines whether the call will do anything useful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (parameters carry only title-level names), so the description must compensate, and it largely does for the critical parameter: it defines the '+' joining syntax, lists the four accepted modifiers, and enumerates valid key names down to F1–F12 and single characters. The second parameter, sandbox_id, is left entirely unexplained, which keeps this from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource plus scope: "Press a single key or a keyboard shortcut on a sandbox's keyboard." That is far more precise than the bare name sandbox_key. It does not explicitly contrast itself with the sibling sandbox_type (text entry) or sandbox_click, so sibling differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied through examples of valid keystrokes and the aside that "super" opens the desktop's application search. There is no statement of when to reach for this tool versus typing text or running commands, and no prerequisites such as the sandbox needing to be started. An agent can infer the use case but gets no explicit routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.