add_apply_point_damage_node

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

No annotations are provided, so the description carries the burden. It explains the behavioral effect (damage with hit location/direction enabling physics reactions) and mentions optional node_position. However, it doesn't disclose side effects like whether the node is automatically connected, whether the blueprint is compiled, or whether existing nodes are affected. The KB reference adds some context but is not a substitute for behavioral 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?

The description is compact and front-loaded with the core purpose. The comparison to Apply Damage is useful, and the Args list plus example are efficient. The KB reference is a minor addition. No wasted sentences, though the example could be more illustrative.

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 node-adding tool with 3 parameters and no annotations, the description covers the basic purpose and parameters but lacks details on node placement behavior, connection defaults, and post-add actions (e.g., compile). The output schema exists but the description doesn't explain what the tool returns. The KB reference helps but is not fully self-contained.

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%, so the description must compensate. It lists all three parameters (blueprint_name, damage_amount, node_position) with brief explanations, but the explanations are minimal and mostly restate the parameter names. It doesn't clarify the format of node_position (e.g., [X, Y] coordinates relative to what) beyond the example, and damage_amount's units/range are unspecified. The example shows usage but not parameter details.

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 tool adds an 'Apply Point Damage' node, specifies it deals damage at a specific world location/direction, and distinguishes it from the similar 'Apply Damage' node by including hit location and direction for physics reactions. It could be slightly clearer about the exact resource (blueprint graph) but the verb 'Add' and the node name are specific.

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 explicitly compares to 'Apply Damage' and explains when this variant is preferred (when physics reactions like pushback from projectile impact are needed). It doesn't explicitly state when NOT to use it or name the sibling tool add_apply_damage_node, but the comparison provides clear context for selection.

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