manage_scene_structure

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It lists three actions but does not state whether the tool rewrites the .tscn file on disk, whether rename updates references to the node, whether duplicate copies child nodes and properties, whether move adjusts parent transforms, or whether changes are persisted immediately. These are significant unknowns for a mutation tool.

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 very concise and contains no filler, but it is closer to under-specification than to appropriately sized guidance. It is a single short phrase that communicates the core action but omits essential behavioral and conditional context that would make the length appropriate for a multi-action tool.

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?

This is a multi-action tool with six parameters, no annotations, no output schema, and many closely related sibling tools. The description provides only a high-level summary of the three operations and fails to explain per-action behavior, parameter dependencies, file mutation effects, or success/failure semantics. An agent would need significant additional inference to use it reliably.

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 each parameter is already described with basic meaning. The description adds little beyond naming the three actions, which the schema already lists. It does not clarify conditional parameter requirements, such as when newName vs newParentPath should be supplied, so it provides only marginal added value over the schema.

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 names a specific verb-resource pair: 'Rename/duplicate/move nodes within .tscn scenes.' This clearly communicates the primary function and the file type it targets. However, it does not explicitly distinguish itself from sibling tools like modify_scene_node or game_reparent_node, so it falls short of a 5.

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 provides no guidance on when this tool should be used versus alternatives such as modify_scene_node, add_node, remove_scene_node, or game_reparent_node. It also does not clarify whether this operates on static scene files versus runtime scene tree manipulation, leaving the agent to infer the appropriate context.

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