Hold a key down

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

Annotations already declare readOnly=false and idempotent=false, but the description adds real lifecycle behavior not in the schema: the key remains held until released, and held keys are auto-released if the process exits. That process-exit caveat is exactly the kind of context annotations can't convey.

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?

Front-loads the critical semantics ('stays pressed until release_key') before the long key enumeration. The key list is lengthy but earns its place given 0% schema coverage; minor redundancy with 'arrows up down left right'.

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?

For a one-parameter, no-output-schema tool this covers the essentials: hold semantics, the release counterpart, valid key names, and process-exit cleanup. Only gap is behavior on repeated calls with the same key, which is a minor omission.

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% for the single 'key' parameter, so the description carries the full burden — and it does, enumerating accepted key names (W/A/S/D, space, enter, esc, tab, modifiers, arrows, f1-f12, letters/digits). The 'letters/digits' bucket is vague on case/format, so it falls just short of fully specifying syntax.

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?

States a specific action ('key stays pressed until release_key') and names the complementary tool, which cleanly distinguishes it from the sibling press_key (a momentary tap). An agent can tell immediately that this is the sustained-input tool.

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?

Gives concrete usage context ('use for movement (W) and camera') and points to release_key as the terminating call. It stops short of an explicit when-not (e.g., 'for a single tap use press_key instead'), so the routing decision against the sibling is implied rather than spelled out.

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