Swap two windows' placement slots

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the core action and mentions verification ('Verified with fresh geometry afterwards'), which adds a small behavioral detail. However, it does not disclose side effects, required permissions, error handling for invalid positions, or impact on other layout properties. This is insufficient for a mutating tool with zero annotation coverage.

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 two sentences with no filler. The core action is front-loaded, and the verification note adds a useful detail. It is appropriately sized for the tool's simplicity, though the second sentence could be seen as slightly tangential.

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 tool with no annotations and no output schema, the description is thin. It leaves unanswered questions: What happens if positions are out of range? Does it return anything? What is the 'fresh geometry' verification exactly? Given the complexity is moderate (swapping two positions), more context about error handling and expected results would be needed for an agent to call it safely.

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 schema provides no descriptions (coverage 0%), so the description must compensate. It clarifies that a and b are positions in layout_order (1-based), which is crucial meaning beyond bare integer parameters. However, it does not explain the 1-20 range or behavior for out-of-bounds values. It adds key context but not completeness.

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: exchange the placement order of two windows, using positions in layout_order as the identifier. It specifies the resource (grid/master placement) and the method (1-based positions). However, it doesn't explicitly name a sibling alternative, so it's strong but not at the level of differentiating itself from tools like window_swap.

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?

There is no explicit when-to-use or when-not-to-use guidance. While the phrase 'by their positions in layout_order' suggests this is for layout order manipulation, it does not clarify when to prefer this over window_swap (which might swap by ID) or layout_tomaster. An agent would have to infer usage from the description alone.

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