production.physics_generate_secondary_bones

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the mutation profile is partly covered. The description adds real value beyond that: it says the scope is limited ("Body/face preserved") and that it works off a "fixed physics plan" with "explicit QA/review gates", which tells the agent it is gated rather than free-form. It does not say what a re-run with apply=true does to existing bones, nor what happens on non-idempotent repeats.

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 short sentences, front-loaded with the operation and modes, with the safety default (apply=false) stated early. Dense jargon like "fixed physics plan" costs some clarity, but there is no filler.

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?

Although an output schema exists and return values need not be described, a seven-parameter, non-idempotent mutation tool with zero parameter documentation needs more than this. The agent cannot know what to pass for physics, object_name or operation_id, or what prerequisites the QA/review gates impose before apply=true.

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% for seven parameters, so the description must carry the burden. It only explains one of them (apply, default false) and vaguely alludes to the physics plan. brief, intent, options, physics, object_name and operation_id are completely uncharacterized, including how operation_id relates to the review gates.

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 operation ("inspect, propose, or execute physics_generate_secondary_bones") and its target ("isolated secondary candidates"), which conveys the tri-modal workflow. But restating the tool name is tautological, and it never distinguishes this from the many adjacent physics generators (physics_generate_hair_secondary, physics_generate_soft_secondary, physics_generate_accessory_motion), leaving the agent unable to tell which secondary type this covers.

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?

"Inspect, propose, or execute" plus "apply defaults false" implies the mode ladder: default is non-mutating inspection/proposal and apply=true executes. That is implied usage guidance rather than explicit, and there is no when-not-to-use or pointer to the sibling generators that handle hair/soft/accessory secondaries.

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