Create or update a layout

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

With no annotations supplied, the description carries the full burden and does so thoroughly: the confirmation-free command only on create, one set request per supplied field, mandatory read-back after every property write, abort-and-inspect on uncertain writes, name/occupancy checks, and no fallback via Lua or OSC. It also discloses that mutations are only serialised within this server and not isolated from another operator, which is exactly the caveat an agent needs before writing.

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 purpose is front-loaded in the first clause and subsequent sentences are dense but non-redundant, each covering a distinct constraint (units, verification scope, exclusions, fallbacks, concurrency). Some sentences are overloaded run-ons that would read better as short bullets, but nothing is wasted 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 16-parameter mutation tool with no annotations and no output schema, the description covers safety, units, verification and concurrency well. It stops short of explaining the boolean options or what the read-back actually returns, which is a real gap when no output schema exists to define the response shape.

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% across 16 parameters, so the description must supply meaning, and it does for units and ranges: canvas position/size are Int16 layout units, view coordinates Int32, and view_scale is a positive ratio where 0.8 means 80% with percent shown on read-back. However, the booleans (markers, value_colors, view_position_active) and name/note semantics are never explained, leaving roughly half the parameters understood only by name.

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 opening sentence names a specific verb pair and resource ('Create a new empty layout or update only supplied layout fields') and scopes it to an explicit data pool. The mode enum and the statement that it 'never deletes or rebuilds elements' separate it from layout element editing and read-only layout listing. An agent can tell what this mutates without opening the schema.

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?

It gives clear operating context: create refuses an occupied number, preview reads and validates without mutations, and Layout Viewer window/grid/fit setup is explicitly out of scope. What it lacks is any named sibling routing (e.g. gma3_layouts for reads vs gma3_edit_layout_elements for element work), so the agent must infer that boundary itself.

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