sw_generate_propeller

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation profile is covered. The description adds real geometric behavior not in structured fields — the twist law atan(P/2πr), the presence of a hub and bore, and that the result is aligned along Y with thrust in +Y — but says nothing about which document the feature lands in, whether an existing body is modified, or failure modes.

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?

Two short clauses, front-loaded with the object being generated and the key geometric convention; no filler. It is terse to the point of omitting a verb, but nothing in it is wasted.

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?

A 12-parameter generative/mutating tool with no output schema needs more: which document it writes into, whether units are uniformly mm, whether the blade profile comes from the airfoil or the chord params, and what the agent gets back. The orientation and formula help, but the definition is too thin for this parameter surface.

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 50%; blades, sections, tip_chord, root_chord, hub_length and hub_diameter carry no schema descriptions. The description partially compensates by tying pitch to radius in the twist formula and naming the hub and shaft bore, effectively explaining pitch, diameter, and shaft_diameter, but the chord/section/blade parameters remain opaque in both places.

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 identifies the resource precisely — a propeller with twisted blades, hub, and shaft bore — and even states the pitch-angle formula and orientation. It stops short of an explicit verb ('generates') and does no differentiation from siblings like sw_generate_wing or sw_generate_fuselage, but an agent can still tell what object is produced.

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?

There is no guidance on when to use this versus sw_generate_wing/sw_generate_fuselage/sw_generate_part, no prerequisites, and no mention of whether it requires an open part document or creates one. The only usage hint is structural (axis Y, thrust +Y), which is orientation, not selection criteria.

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