Open an app into a chosen split (verified)

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

No annotations are present, so the description carries the full burden. It discloses a critical behavioral trait: the tool does not just act — it VERIFIES on-screen and returns a verdict with correction hints, meaning failures are surfaced rather than silently succeeding. It stops short of stating permission requirements, failure modes, or side effects on the existing focused window, but covers the essential behavioral contract.

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?

Four tight sentences, front-loaded with the primary action and verification trait, followed by return-value disclosure and a concrete example. No filler or redundant restating of the title. The structure lets an agent grasp the core behavior in the first sentence.

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?

No output schema exists, so the description correctly explains return values (landed window geometry plus a verdict with correction hints). It covers purpose, verification behavior, and return contract for a moderate-complexity tool. It could add failure/fallback behavior and permission notes, but under the absence of annotations it covers the needed ground well.

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?

With schema coverage at 75%, the schema already documents command, refocus, and args well. The description adds value above the schema by clarifying direction semantics via the example (direction='d' opens below the focused window) and illustrating how direction pairs with the command parameter. This is a modest but genuine addition beyond the enum definition.

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 states a specific compound action — preselect a split direction and launch a command — then names the distinguishing trait: on-screen verification that the window actually tiled. This clearly separates it from sibling tools like layout_preselect (preselects without launching) and launch_app (launches without split control). The concrete example (direction='d', app='terminal') reinforces the intent.

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 implies its use case (launch an app into a preselected split and verify) but provides no explicit when/when-not guidance or named alternatives. Given the large sibling set of layout tools (layout_togglesplit, layout_preselect, window_snap, layout_mode), an agent gets no direct help distinguishing optimal choice beyond the implied launch+verify behavior.

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