Press keys

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two facts annotations cannot convey: each entry is both pressed and released (so a modifier chord like ramiga+q is a complete keystroke, not a held state), and input is delivered to the active window, which matters for stateful desktop automation. It stops short of saying what happens if the target window is not focused or whether errors are reported.

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-loaded with the action and target, then the accepted key forms, then the alternative-tool pointer in a single compact statement. It is one long semicolon-delimited sentence, which is dense but every clause (vocabulary, modifier syntax, raw code, sibling routing) carries information an agent needs; only the punctuation structure slightly hurts scannability.

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 tool with full schema coverage and no output schema, the description covers everything needed to call it correctly: target window, accepted key formats, press-and-release semantics, and where to go for text entry. The only gap is failure behaviour (no focused window, unsupported key name), which is minor given the tool's simplicity.

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 100% and the parameter is a plain string array, so the baseline would be 3. The description nevertheless adds substantial meaning the schema lacks: the enumerated key vocabulary (return, esc, tab, del, backspace, space, f1-f10, arrows, help, kp0-kp9, kpenter), the '+'-joined modifier syntax with named Amiga modifiers (ramiga, lamiga, ctrl, shift, alt), and the raw hex escape hatch (0x45). Since the schema exposes no enum, this list is the only place the accepted values are specified.

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 verb and resource ("Press keys ... into the active window") and immediately scopes the accepted key vocabulary: named keys, modifier combinations joined with '+', or raw hex codes. It explicitly names the sibling it is not for ("For ordinary text use amiga_key_type"), so an agent can distinguish it from amiga_key_type without opening either schema.

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 explicit routing guidance to the alternative tool for ordinary text input, plus a clear statement of the target (the active window). It does not cover other plausible alternatives (e.g. amiga_ui_click for actuating UI controls, amiga_input for bulk input), but the primary ambiguity between typing and pressing is resolved.

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