instance_clone

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the original instance's descendants are cloned, but it does not mention whether the original is left unchanged, how naming conflicts are resolved when newName is omitted, or whether property overrides mutate the clone versus the schema defaults.

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?

A single, focused sentence communicates the action, the scope, and the destination with no wasted words. The core verb 'Clone' and the resource scope are front-loaded.

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 recursive clone operation with no annotations and no output schema, the description is too thin. It omits important operational details like whether the original is affected, conflict handling, expected return value, and any restrictions on the target parent relative to the source subtree.

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 100%, so the baseline is 3. The description reinforces the meaning of target and parent but does not add meaningful detail beyond the schema's own parameter descriptions, such as formatting rules for paths or behavior of the properties object.

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 description clearly states the action: 'Clone an existing Instance (and all its descendants) and place it under a target parent.' This distinguishes it from sibling tools like instance_create, instance_reparent, or instance_move by emphasizing the cloning of the full descendant subtree.

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 this tool should be used: when an existing instance and its descendants need to be duplicated under a parent. However, it does not explicitly name alternatives or state when not to use it, such as when creating a blank instance or moving an existing one would be more appropriate.

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