Set omarchy-grid layout mode

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It does state that it 'switches' the active workspace and mentions that it 'Returns the layout's own confirmation,' but it does not elaborate on side effects, reversibility, or any prerequisites. The phrase 'layout's own confirmation' is vague and leaves the return format unspecified. This is acceptable for a simple tool but lacks the depth expected without annotation support.

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 totaling roughly 45 words. The primary action is front-loaded, followed immediately by the mode definitions, and the return behavior is stated in the second sentence. There is no fluff or redundancy; every sentence earns its place.

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 simple tool with one parameter, the description covers the core usage and return behavior. However, it does not specify the exact format of the confirmation or mention potential errors or edge cases. Given the lack of an output schema and annotations, an agent might need additional context to handle unexpected responses. The description is adequate but not exhaustive for a tool in a large sibling set where branching behavior could matter.

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 must compensate for the parameter. It does so effectively by explaining the two allowed values: 'grid' and 'master' with detailed parenthetical descriptions. This adds meaning beyond the raw enum and helps an agent understand the semantic impact of each choice. The parameter name 'mode' is self-evident, and the description fully covers its meaning.

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 tool's purpose: switching the active workspace between the two layout modes 'grid' and 'master'. It describes each mode in concrete terms (deterministic row-major cells vs. first window full-height left column), making the action unambiguous and distinct from other layout-related siblings like layout_togglesplit or layout_grid.

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 explains what the tool does but gives no explicit guidance on when to use it versus alternative layout tools. Sibling tools such as layout_grid, layout_tomaster, and layout_togglesplit exist, yet the description does not mention them or specify conditions that would favor one over another. The usage context is implied (when you want to switch between grid and master), but no exclusion criteria or alternative recommendations are provided.

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