set_node_reference

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

Annotations establish the mutation/safety profile (readOnly=false, destructive=false, openWorld=true), and the description adds genuinely non-obvious behavior: it executes project constructors and preserves existing script references. That explains the openWorld hint and warns of a side effect. It still does not describe failure modes or what state must exist beforehand.

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 with the purpose front-loaded and no filler; the secondary sentence about constructors/references carries real information. Brevity comes at some cost of clarity around 'compatible' and 'preserves script references'.

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 5-required-parameter mutation tool with no output schema and no annotations covering inputs or preconditions. The description says nothing about what a 'compatible' node is, what happens on mismatch, whether the project/editor must be loaded, or what is returned.

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 0% and there are 5 required string parameters with no documentation anywhere. The description only vaguely gestures at 'property' and 'targetNodePath' ('compatible node'), leaving projectPath, scenePath, and nodePath entirely undefined, including whether nodePath is the source node or the destination.

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 ('Bind') and resource (an exported Node/NodePath script property to a target node) with a clear scope constraint ('in the same scene'). It is distinguishable from generic writers like set_node_properties, though it never names a sibling to contrast with.

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 'same scene' constraint implies when this applies, but there is no explicit when-to-use, when-not, or alternative (e.g., set_node_properties, modify_scene) for rewiring references. Usage must be inferred.

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