sw_cosmetic_thread

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

Annotations only say it is a non-destructive write; the description adds real semantic content by explaining that the thread is cosmetic/lightweight and is represented as drawing annotation rather than modeled geometry. It still doesn't say what happens to an existing thread on the same edge or what the tool returns, but the key behavioral distinction is disclosed.

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?

One sentence with zero filler, front-loading the resource and the defining cosmetic/lightweight trait before the placement constraint.

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 feature-creating mutation with five parameters and no output schema, the description leaves meaningful gaps: the optional 'length' has no explanation anywhere, the supported size format breadth is unclear, and there is no note about the required pre-existing circular edge or error behavior.

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 coverage is 80% and the schema already documents size ('M6', 'M10x1.25') and edge_point ('Point on the circular edge'). The phrase 'on a shaft or hole edge' reinforces edge_point but adds no new format or constraint information, and the undocumented 'length' parameter is not clarified in the description.

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 specific verb+resource ('Cosmetic thread') and its location constraint ('on a shaft or hole edge'), plus the qualifying trait 'lightweight, shows in drawings'. It does not explicitly distinguish itself from the sibling tools sw_thread and sw_hole_wizard, which an agent could easily confuse with this one.

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?

Usage is only implied: cosmetic threads go on circular edges of shafts or holes. There is no explicit 'use this instead of sw_thread when...' guidance, and no prerequisites (existing edge, active document) are stated.

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