press_keys

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

The description explains multi-key behavior and mentions background delivery via window handles is 'without focus'. However, annotations already indicate destructuring false, so safety profile is decent. The description does disclose the fallback approach (prefer_ahk) somewhat through schema. It adds that keys are delivered without focus for background targets, which is useful. There's no mention of focus disruption consequences, but the confirm_focus_disruption parameter exists in schema. Score 3: adds some behavioral context beyond annotations.

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 description is compact: a one-line purpose statement, a sentence about single vs multiple keys, and a brief note about background delivery appearing to be within arg descriptions. The 'Returns' line is redundant given the output schema exists. Overall efficient without bloat, appropriate length for the tool's complexity.

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?

Given the tool has a rich nested schema with 6 well-documented parameters including background targeting options (hwnd, window_title, display) and an output schema, the description covers the core purpose and multi-key semantics. However, it doesn't note the ahk_status/sibling relationship for AutoHotkey-dependent features. The description is adequate for most uses but doesn't differentiate from win_send_keys or type_text adequately in body text.

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 0%, meaning the input schema descriptions are the primary documentation. Each parameter (keys, hwnd, display, prefer_ahk, window_title, confirm_focus_disruption) has a detailed description in the schema itself. The tool description adds the multi-key combinational semantics and the pyautogui key name note, but these are also largely in the schema. Since schema covers parameters well despite 0% 'description coverage' metric (which refers to the tool description), the description adds marginal value over schema. Score 3: schema does most of the heavy lifting.

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 clearly states 'Press a keyboard combination (hotkey), e.g. Ctrl+C or Alt+Tab' with a specific verb (press) and resource (keyboard combination/hotkey). It distinguishes from siblings like type_text (which types literal text rather than key combos) and win_send_keys by its explicit hotkey framing. Score 4: clear purpose, though it doesn't explicitly contrast with win_send_keys, which is a closely related sibling.

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 states when to use it implicitly (to press hotkeys/combinations) but doesn't explicitly say when NOT to use it or name alternatives like win_send_keys. The sibling win_send_keys is very similar but the description provides no differentiation guidance. The single vs multi-element list semantics give functional usage guidance though. Score 3: functional guidance present, but no explicit alternative/exclusion guidance.

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