Unmerge elements

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so safety/behavior basics are covered. The description adds valuable return-shape detail ({results:[...], removedCount} with per-item removed/error), which is beyond what annotations provide. It doesn't mention auth or whether removed merges are reversible, but the return contract is a genuine addition.

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?

Two compact sentences, front-loaded with the action and inverse reference, then the parameter modes and return shape. No filler; every clause carries information.

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 destructive mutation with no output schema, the description supplies the return shape, the parameter modes, and the inverse-operation link. Missing only edge details like limits (maxItems 1000/5000), behavior when a merge doesn't exist, and any permission requirements, but it is largely sufficient to call correctly.

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 coverage is only 50%, so the description must compensate, and it partly does: 'give pairs [{element, otherElement}] and/or elements (all merges of these)' clarifies that pairs targets specific connections while elements removes all merges of an element. This adds meaning beyond the schema, though it doesn't explain the guid-object alt form, maxItems limits, or overlap semantics between the two params.

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?

States a specific verb+resource ('Removes merge connections') and explicitly ties it to the inverse operation ('created by merge_elements'), which is a named sibling. An agent can immediately distinguish it from merge_elements and remove_solid_operation.

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 names the originating operation (merge_elements) and the two input modes (pairs and/or elements), implying when each applies. However, it doesn't state when to use pairs vs elements, nor any prerequisites (e.g. does the merge need to exist, error handling). Usage is implied rather than explicit.

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