promote_kit_piece

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

There are no annotations, so the description carries the full behavioral burden. It adds useful context that lineage remains intact and that Kiln Pro is required, but it does not say what happens to the original kit piece, whether the operation is reversible, what permissions are needed, or what errors may occur.

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 core action is front-loaded in a strong first sentence, but the rest of the description is largely plan marketing and an upgrade URL rather than tool-selection guidance. That material does not earn its place in a concise tool definition.

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?

This is a mutation tool with no annotations, no output schema, five parameters, and only partial schema description coverage. The description should do more to explain side effects, preconditions beyond licensing, and how the inputs map to the promoted piece and new design.

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 only 60%, and the required fields design_id and new_design_id have no descriptions in the schema. The description hints that one input identifies the kit piece and another identifies the new standalone design, but it does not clarify the roles of kit_id, piece_label, or name.

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 first sentence gives a specific verb, resource, and outcome: promoting one kit piece into its own standalone design while preserving lineage. It is clear what the tool does, though it does not explicitly distinguish itself from nearby kit-related siblings such as plan_kit_plates or advise_kit_scale.

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 states a licensing prerequisite, 'Requires Kiln Pro,' but gives no guidance on when to use this tool versus alternatives or when not to use it. The implied use case is only inferable from the tool name and first sentence.

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