add_physics_asset_constraint

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description reinforces the idempotency by explaining re-using a name returns the existing joint. It goes beyond annotations by disclosing the default Limited swing+twist cone, the conditional frame snap to the bones' default relative transform, and the reason snapping is skipped (engine fatal-checks unknown bones). It does not cover permissions or rate concerns, but for this tool that is minor.

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 creation semantics are front-loaded in the first sentence, with the idempotency, default cone, and snapping caveat following in a tight block. It is somewhat dense and the phrase 'skipped honestly otherwise' is chatty, but nothing is wasted given the mutation and its conditional behaviors.

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?

There is no output schema, so the embedded Returns block listing every returned field (already_existed, frames_snapped, body indices, save_error, note, etc.) is genuinely necessary and is present. Combined with the disclosed default behavior and idempotency, an agent has everything needed to call this mutation correctly.

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% and each of the four parameters carries its own description, so the schema does the heavy lifting. The description adds only marginal semantic context ('between two bones', 'sets the child/parent bones') that is already implied by the property descriptions; baseline 3 is appropriate.

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 and resource: authoring a ragdoll constraint (joint) inside a UPhysicsAsset between two bones. It distinguishes itself from neighbors by naming the follow-up tool (set_physics_asset_constraint_limits) and by describing the default cone and frame-snapping behavior an agent can expect.

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 makes clear this is the creation step and explicitly routes the agent to set_physics_asset_constraint_limits for refining motions/limits afterwards. It explains the conditional frame-snapping path, but offers no explicit when-not-to-use guidance or mention of remove_physics_asset_constraint as the undo path.

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