production.physics_setup_cloth

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

Beyond annotations, it discloses that apply defaults to false (safe default), that a fixed physics plan and explicit QA/review gates apply, and that body/face are preserved. These are meaningful behavioral constraints for a mutation-capable tool. It does not state permissions or full side effects, but the added context is strong relative to the annotation baseline.

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 dense sentences, front-loaded with the operational modes, followed by preservation and safety gates. It is compact and mostly earns its place, though 'isolated secondary candidates' and the final semicolon clause are terse to the point of being cryptic.

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?

An output schema exists, so return values need not be explained. However, seven optional parameters with zero schema descriptions and no usage routing against many physics siblings leave substantial gaps. The description covers safety defaults and preservation but not enough of the parameter surface or sibling selection to call it complete.

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 for all seven parameters. It only clarifies the apply parameter (defaults false); brief, intent, options, physics, object_name, and operation_id remain completely opaque in both schema and description.

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 the modes (inspect, propose, execute) and scope (isolated secondary candidates), but 'physics_setup_cloth' itself is not explained in terms of what a clothing physics setup actually configures. It only weakly differentiates from siblings like physics_simulate_cloth or physics_plan_cloth_pins by mentioning 'isolated secondary candidates' and 'Body/face preserved'.

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 phrase 'apply defaults false; fixed physics plan and explicit QA/review gates' implies usage: use with apply=false to propose, and expect explicit QA/review. However, there is no explicit guidance on when to choose this tool over physics_simulate_cloth or physics_plan_cloth_pins, nor any stated exclusions.

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