add_hem

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

With no annotations, the description carries the full behavioral burden and does most of it well: it discloses that geometry is added on the reverse side, that the cloth cannot be folded (only ~20 degrees), and that overlapping strips on the same layer crumple. It does not state permissions, undo/persistence behavior, or whether the operation is reversible, which keeps it short of a 5.

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?

Purpose is front-loaded and the Args block is ordered, so it is easy to scan. It is slightly bloated by parenthetical digressions (the fold-angle aside) that delay the argument list, but nearly every sentence carries usable information.

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 six-parameter mutation tool with no annotations and no output schema, the description covers what is produced ('the doubled fabric at the edge') and how placement works, which is sufficient to call it correctly. It stops short of covering failure modes or undo/persistence, a minor gap given the richness elsewhere.

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 fully compensate, and it does: it documents all six parameters, including units for width (mm), the source of line_index (get_pattern_geometry / view_patterns), the default for fabric_index, and the default meaning of place_flat. The layer parameter is explained in unusual depth, including -1/1 axis meaning and the -2 convention for crossing hems.

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?

States a precise verb+resource ('Hem a straight edge') and then explains the mechanism: a turned-back strip sewn along the edge and a new hem line, producing doubled fabric at the edge. This is specific enough to separate it from neighboring construction tools like add_applique or make_rod_pocket without opening any schema.

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 implies the use case (hemming a straight outline line) and gives a conditional rule for place_flat ('set False and place it yourself for pieces on an avatar'), but it never names an alternative tool or states explicitly when this should be chosen over them. Usage context is present but inferred rather than stated.

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