prepare_outfit_slot_reference

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

With no annotations, the description carries the burden, and it does disclose the write side effect, the underlay being alignment/proportions only and not a clip mask, and the transparent paint target. It does not, however, state overwrite behavior, prerequisites, failure modes, or whether scale/output_dir change the output path.

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 dense but efficient, leading with the mandatory use, then output path, key semantics, an example, and the allowed paint tools. Each sentence adds information, though the mix of conceptual semantics and workflow instructions could be better separated.

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?

It is complete enough to make the basic required call with name and slot and to understand the generated artifact, and an output schema exists for return values. It is incomplete for optional parameters (scale, plan_id, output_dir) and does not explain how the reference integrates with plan_outfit or generate_outfit_slot.

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, but it only defines 'slot' (one of the 10 export layer names) and implicitly shows 'name' in an example. scale, plan_id, and output_dir are left undefined.

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 states a concrete outcome: it writes design/refs/<layer>_ref.png as a mandatory preparation step before painting, with body-part underlay and design layer semantics. It distinguishes the tool from paint/fill siblings by framing it as the reference-preparation step and naming later paint tools.

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?

It explicitly says 'MANDATORY before/during paint' and prescribes the follow-up workflow using fill_parts_on_slot, fill_rect, draw_line, paint_pixels, and paint_from_commands. It also gives an exclusion ('never Shell/PIL or GenerateImage'), though it does not contrast with sibling generate_outfit_slot or plan-related alternatives.

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