Snap any window to a corner (verified)

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

With no annotations, the description must carry the full behavioral burden. It discloses the multi-step process (float, pin, resize, position, verify) and the targeting methods (address or substring match). However, it does not disclose potential failure modes, reversibility, or side effects on the window's state (e.g., whether it persists across sessions). Verification is mentioned but not what happens on failure. Thus it covers core behavior but lacks depth.

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?

Three sentences (plus an example) with no unnecessary words. The action is front-loaded, the targeting method is explained, and the default size and a usage example are provided. Every sentence adds value and is easy to scan.

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 an 8-parameter tool with no output schema and no annotations, the description covers the core purpose and gives an example, but it does not explain the margin parameter, the effects of pin (beyond the schema description), or behavior when the window is not found. The default size hints at width/height, but corner values and margin semantics are left to the schema (which lack descriptions). While the example reduces some ambiguity, the tool complexity suggests more context would be beneficial.

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 50% (pin, match, address, monitor have descriptions; width, height, corner, margin do not). The description adds meaning for match (substring, example 'chrome') and corner (via example 'br'), and clarifies default size (1300x900) which informs width/height defaults. However, it does not elaborate on width, height, margin, or the corner value meanings themselves. It partially compensates for the missing schema descriptions but leaves the numeric parameters underexplained.

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 the action: 'Float + pin + resize + position ANY window to a corner of the focused monitor, then verify on-screen.' It specifies the verb (snap/position), resource (any window), and the precise outcome (corner of focused monitor). It also distinguishes from the sibling self_window_snap by targeting ANY window, and provides a concrete example that clarifies the use case.

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 a clear usage example (launch_app then window_snap) implying when to use this tool for positioning a window. However, it does not explicitly state when NOT to use it or mention alternatives like window_resize or window_float_toggle for simpler operations. The context is clear but exclusionary guidance is absent.

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