add_collision

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

No annotations are supplied, so the description carries the full disclosure burden and does well: it explains the observable effect of the missing setup, that this is a mutating add operation, and what is returned ('Dict with the collision settings'). It omits whether re-applying overwrites existing settings or what happens on an invalid object_name.

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-loaded one-sentence purpose, then a motivating consequence, then a clean Args block ordered by importance with only the required parameter first. Every sentence adds information; ranges are not duplicated from the schema since the schema lacks them.

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 6-parameter mutation with no annotations, the description covers the effect, the failure mode it prevents, all parameter semantics and ranges, and return shape. An agent has everything needed to call it correctly; the Returns section is mildly redundant given the output schema but harmless.

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 the schema has no minimum/maximum, yet the description documents all six parameters with ranges (thickness 0.001-1.0, friction 0-80, stickiness 0-10, damping/permeability 0.0-1.0) and semantic meaning — damping as bounce loss, permeability as share of particles passing through. This is substantial compensation for the schema gap.

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 effect ('make an object solid to cloth, particles and soft bodies'), which pins down both the resource and the physics domains it applies to. The domains named (cloth/particles/soft bodies) implicitly exclude the rigid-body siblings, so an agent can distinguish it from add_rigid_body or add_cloth_sim.

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?

'Without it, a cloth falls straight through the floor' gives a concrete condition for when the tool is required, and 'Raise it if cloth pokes through' gives troubleshooting guidance. It stops short of naming alternatives or stating exclusions (e.g. when rigid-body collision is the better choice).

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