add_warp_target_to_component

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

Annotations already declare idempotentHint=true and destructiveHint=true; the description adds the mechanism behind idempotency (replace-in-place keyed by WarpTargetName) and the editor side effect (marking the owning actor dirty so the change persists). It does not spell out failure behavior when the component or target is absent, but it meaningfully enriches the annotated profile rather than merely restating it.

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?

Front-loads the purpose and the required payload shapes in a single dense paragraph with no filler sentences, and the trailing Returns block is justified because no output schema exists. The inline C++ signature fragments (AddOrUpdateWarpTargetFromComponent args) add length that a plain-English gloss could have shortened.

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?

With no output schema, the description correctly documents the return shape (actor_path, target_name, warp_target_count, source, already_existed), and it covers the required actor_path/target_name pairing, the three accepted payloads, and replace-in-place persistence. It omits what happens on a missing MotionWarpingComponent or an invalid payload combination, which is the main remaining gap.

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 100%, so the per-parameter descriptions already carry the baseline; the description adds cross-parameter semantics the schema cannot express by mapping which parameter combinations select which engine entry point. That is real value above baseline, though it stops short of detailing defaults or error cases for malformed payloads.

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+resource ('Add (or update in-place) a FMotionWarpingTarget') and constrains the target host to 'an existing UMotionWarpingComponent', which separates it from the sibling add_motion_warping_component that creates the component itself. An agent can tell what this tool does without opening the 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?

Provides strong invocation conditions: 'Exactly one of three payload shapes must be supplied' with each shape spelled out (component_path / location+rotation / location only). It does not, however, explicitly say when to prefer this over siblings like set_motion_warping_target_location, set_motion_warping_target_rotation, remove_warp_target, or list_warp_targets_on_component, so exclusions are left implicit.

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