save_layout

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

With no annotations, the description carries the full burden and reveals key behaviors: 'Saving over an existing name replaces it' (destructive action), 'Saved workspaces are listed in get_state' (integration), and the different semantics of omitting vs. passing 'items' (snapshot vs. explicit layout). It does not mention return values or explicitly say whether running apps are moved, but it indirectly signals that save_workspace has that capability, implying save_layout does not.

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 three concise sentences that front-load the main purpose, then provide alternative guidance and parameter nuances. Every sentence carries essential information with no redundancy or filler.

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 save operation with no annotations and no output schema, the description effectively covers purpose, usage conditions, alternatives, replacement behavior, and integration with get_state. However, it does not explicitly state that this tool only saves (does not apply the layout now), which would be useful context given the sibling apply_saved_layout, and it omits any mention of return values.

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 description adds meaning beyond the schema by explaining the practical effect of omitting 'items' vs. providing it: 'Omit 'items' to snapshot the windows exactly as they are on screen right now; pass 'items' to describe the arrangement explicitly.' It also clarifies that the 'name' parameter overwrites existing workspaces ('Saving over an existing name replaces it'), which is not evident from the schema alone.

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 first sentence, 'Save the named window arrangement as a workspace,' states a specific verb ('save') and resource ('window arrangement as a workspace'), clearly defining the tool's function. It also distinguishes itself from sibling save_workspace by noting it's a 'legacy name' and directing new integrations to the alternative, removing ambiguity.

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 explicitly advises when to use alternatives: 'new integrations should call save_workspace,' which also 'can record whether running apps get moved into place.' It also provides conditional usage for the 'items' parameter ('Omit... to snapshot... pass 'items' to describe the arrangement explicitly'), giving clear decision criteria.

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