Add, update or remove layout elements

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

With no annotations provided, the description thoroughly discloses mutation and failure behavior: stale identities, locks, and read-only properties are refused; removals target confirmed GUIDs; writes require read-back; and uncertain writes stop the plan. It also covers preview non-mutation, post-edit verification limits, serialization without cross-client isolation, and the absence of macro, sequence, or layout-element execution.

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 front-loaded and nearly every sentence supplies a useful constraint, prerequisite, or boundary. However, it is a very dense single paragraph, and the command-level implementation details make it harder to scan than a short overview followed by grouped operation and safety notes.

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 complex nested batch-mutation tool with no annotations or output schema, the description supplies unusually complete invocation context: prerequisites, per-operation behavior, validation, side effects, verification, concurrency limitations, and explicit non-goals. An agent has enough information to construct edits safely and understand what success does and does not prove.

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?

Despite 0% schema description coverage, the description explains nearly all consequential inputs, including geometry units and ranges, identity provenance, supported object classes, replacement semantics, appearance-pool addressing, text formatting constraints, visibility values, and preview behavior. It adds operational meaning rather than merely restating field names or types.

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 precisely defines the operation and scope: applying up to 100 element edits within one existing layout and data pool. It then distinguishes add, update, and remove behavior and explicitly excludes clearing or rebuilding the layout and configuring Layout Viewer settings.

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 concrete prerequisites for each operation, including required geometry for additions and current element numbers and GUIDs from gma3_layouts for updates and removals. It also explains when replace_object is necessary, how to use preview safely, and which tasks are outside the tool's scope.

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