attach_rig

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

No annotations are provided, so the description carries the full behavioral burden. It discloses concrete behavioral traits: clips MERGE by name into the host's clips, same name = same animation, timelines added, host clip keeps its length, loops refit and one-shots retime. It also describes physics/reactivity per kind (physics strands, IK feet, idle reactions). It stops short of stating permission requirements, reversibility, or persistence guarantees.

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 description is long but front-loaded: the core merge semantics appear in the first sentence before the kind enumeration. Given 0% schema coverage and no annotations, the kind-by-kind detail is functionally necessary rather than padding, and each line conveys distinct information. Some tightening is possible but there is little waste.

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 complex tool with 5 undocumented parameters, no annotations, and no output schema, the description supplies substantial context: merge behavior, all nine kinds with default bones, options, and host-reaction behavior. It omits the project parameter's meaning and any return/validation information, so it is thorough but not fully 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, and it largely does: kind values are exhaustively enumerated with default bones and per-kind options (options.sound, options.tail_mood, options.wing_type, options.slots, options.clips), and name is explained as prefixing the new bones. The project and general bone parameters remain undescribed, leaving a 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?

The opening sentence states a specific verb and resource: 'Plug a sub-rig into a named bone of ANY rig.' This distinguishes it from siblings that build whole characters (rig_biped, rig_quadruped, rig_creature). The purpose is clear, though the differentiation from siblings is implicit rather than stated.

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 explains that kind="" lists available kinds and then enumerates each kind with its default bones and options, which gives de facto guidance on which kind to pick. However, it never states when to use this tool instead of alternatives like rig_biped or secondary, nor any prerequisites or when-not-to-use conditions.

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