hwp_foreground_list_windows

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool lists visible window titles, does not read or edit content, and warns that titles can reveal file names. This is meaningful behavioral context beyond the bare name, though it does not discuss return value structure or any system-level effects—acceptable given the zero-parameter, non-destructive nature.

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 and front-loaded: the first sentence states exactly what the tool does, and the second adds the necessary privacy and usage caveat. No sentence is wasted, and the length is proportionate to the tool's trivial input schema.

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 zero-parameter listing tool with an output schema present, the description covers the core behavioral contract: what it lists, what it does not do, and when it should be called. It is slightly terse around what 'experimental typing choice' means in practice, but the output schema handles return-value details, and the caveat about sensitive file names is strong contextual guidance.

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?

The tool has no parameters, so the baseline is 4. The description makes clear that the tool requires no input and simply lists visible windows. There is no parameter documentation burden for the description to carry.

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: 'List visible Hancom window titles.' It clearly distinguishes itself from read-only and editing tools by stating it does not read document text or edit anything, and the purpose—supporting an explicit experimental typing choice—sets it apart from sibling tools like hwp_foreground_status or hwp_foreground_select_window.

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 condition for use: 'call it only when the user asks to target an already-open Hancom window and is comfortable identifying it.' It also implies when not to use it by clarifying it does not read or edit. It does not name alternative tools or give exclusions beyond the privacy caveat, but the context is clear enough for an agent to decide.

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