clone_node_into_parent

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

With no annotations, the description carries the full burden, and it does disclose a genuinely non-obvious behavioral trait: in auto-layout parents the copy joins the flow unless dx/dy are non-zero, in which case it becomes absolutely positioned. That is real beyond-schema context. It still omits whether the source node is left untouched and what the call returns, so it stops short of full disclosure.

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 tight sentences, zero filler, with the primary purpose front-loaded and the conditional auto-layout nuance following immediately. Every clause 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 6-param mutation tool with no annotations and no output schema, the description covers purpose, accepted container types, and the tricky auto-layout positioning case well. The main gap is the return value (e.g. the new node's id) that an agent would need to chain follow-up calls, plus interaction between index and dx/dy.

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 low (33%), so the description needs to compensate, and it does for dx/dy by explaining their flow-vs-absolute effect, which the bare 'number' schema does not convey. The two required params (nodeId, parentNodeId) and name/index are left to the schema, which is acceptable since name and index are already documented there.

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 (clone), resource (node) and destination (parent container), then enumerates the container types it accepts (frame, section, group, auto-layout, slot, page). This clearly separates it from clone_node (no parenting) and reparent_node/move_node (no duplication) without the agent needing to open another 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?

The description implies when to reach for it (duplicating a node directly into a container) and hints at dx/dy behavior, but never explicitly says when to prefer clone_node + reparent_node or insert_child instead. Usage is inferable but not stated, which is the textbook 'implied usage' level.

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