apply_layout

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

No annotations are provided, so the description carries the full burden of disclosure. It thoroughly explains fuzzy app matching, title substring filtering, screen defaulting, frame coordinate semantics (top-left origin, fractions 0..1), unminimizing behavior, and return value format (per-item success/errors). This exceeds typical transparency expectations.

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 long but every sentence earns its place. It is front-loaded with the core action, followed by a logical breakdown of each field with illustrative examples. The structure guides the reader from high-level intent to specific parameter details without redundancy.

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's complexity (multi-monitor support, coordinate math) and the absence of an output schema, the description is remarkably complete. It explains how windows are matched, how frames are interpreted, the effect on minimized windows, and the return format. It even references get_state for screen indices, tying into sibling tools.

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%, so the description fully compensates. It defines every parameter: 'app' (fuzzy matched), 'title' (substring), 'screen' (index from get_state, defaults to current), and 'frame' (x,y,w,h with concrete examples like left half and bottom-right quarter). The examples make the coordinate system unambiguous.

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+resource: 'Move and resize windows to build a layout.' This clearly distinguishes it from siblings like 'snap_window' (single window) and 'apply_saved_layout' (predefined layout). The scope is well-defined as a multi-window arrangement tool.

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?

Clear context is provided: it explains how to structure items (app, title, screen, frame) and even shows how to target multiple monitors. However, it does not explicitly state when to choose this over alternatives, such as 'apply_saved_layout' or 'snap_window'. It leaves that inference to the agent, making it a 4 rather than a 5.

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