keyboard_type

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

The description discloses two meaningful behaviors beyond the annotations: failure on unrepresentable characters and the VM lock state ('VM remains locked by this session; call vm_unlock when finished'). This is valuable side-effect information that the annotations do not convey, though the exact lock acquisition mechanism is slightly ambiguous.

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?

Two sentences carry a clear action, a behavioral constraint, and a required follow-up action. There is no filler, and the most important operational detail (VM lock/unlock) is included without bloat.

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 tool with three parameters, no output schema, and annotations that do not mention locking, the description covers the key risks: character representability and VM lock state. It is missing explicit semantics for 'interval_ms' and does not clarify how this relates to qemu_keyboard_type, but it is otherwise sufficient for an agent to invoke and clean up after the tool correctly.

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 description coverage is only 33%, so the description must compensate for undocumented parameters. It does add meaning for 'text' by explaining layout-sensitive typing and failure behavior, but it says nothing about 'interval_ms', and 'vm_name' is already documented in the schema. The compensation is incomplete for the parameter set.

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 names a specific action ('Type text') and a precise resource ('the active Windows 98 keyboard layout'), and adds a distinguishing behavioral detail: it fails rather than substituting unrepresentable characters. This makes it clear how keyboard_type differs from sibling tools like qemu_keyboard_type or keyboard_key.

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?

The description gives an explicit follow-up instruction ('call vm_unlock when finished') and implies this tool is for typing text in the active Windows 98 layout. However, it does not say when to choose this tool over alternatives such as qemu_keyboard_type, keyboard_key, or keyboard_hotkey, so usage context is only partially provided.

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