plan_outfit

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

With no annotations, the description carries the full burden. It discloses that it saves to characters/<name>/design/plan.json, returns plan_id and user_facing_summary, enforces overhang rules, and prohibits baking shading in later paint steps. It also clarifies that lower_* includes hands/feet for gloves/boots, which is a nuanced behavior.

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 comprehensive and well-structured with sections, but it is long. Every sentence adds value—the overhang rule, layer semantics, and forbidden actions are all necessary. It is front-loaded with the requirement and workflow, so an agent can quickly grasp the purpose. Slightly more conciseness would be ideal, but no filler exists.

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 planning tool with nested objects and no annotations, the description covers the entire workflow, parameter structure, output format, and constraints. It even notes the next steps and expected behavior. The output schema exists, so return values are not required, but the description provides enough for correct invocation.

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. It details the required plan keys (overall_look, slots with all 10 layer names) and their structure ({skip, visual_notes}). It explains the brief parameter via examples ('samurai') and the name parameter implicitly. It also covers output_dir implicitly by mentioning the save path.

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 opens with 'REQUIRED before painting clothes: lock an outfit plan from a free brief,' which is a specific verb (lock/plan) and resource (outfit plan) with clear context. It distinguishes itself from siblings by being the planning step in a defined workflow, and it states the agent authors the plan from the brief, not hardcoded styles.

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 explicitly states when to use it ('REQUIRED before painting clothes'), gives the full workflow sequence (plan_outfit → prepare_outfit_slot_reference → paint → plan_shading → shadow → compose_character), and provides exclusions ('Do NOT invent if-samurai code paths', 'FORBIDDEN: Shell/PIL scripts'). It also tells the agent to show the summary to the user before painting.

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