etabs_run_shear_wall_design

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

Annotations only give the generic non-readOnly/non-destructive profile; the description adds the genuinely important hidden behavior that no API call exists and the server drives the operation through Windows UI Automation, requiring a visible ETABS window. It stops short of disclosing whether design results are written into the model or whether the call blocks for a long-running design.

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?

Three sentences, zero filler, front-loaded with purpose before implementation caveat and prerequisite. The menu path is compact and useful for cross-referencing etabs_menu.

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?

With an output schema present, return-value explanation is unnecessary, and the description covers the unusual invocation mechanism and prerequisites. It could still note the failure mode when pier/spandrel labels are absent or that the run may take time, but what is there is sufficient to call it correctly.

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?

There is a single parameter with 100% schema description coverage ('Pier/spandrel rows to return, worst first.'), so the schema already carries the semantics. The description adds nothing about limit, so the baseline 3 applies.

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 names a specific verb and resource ('Run shear wall design') and specifies the artifact returned ('pier and spandrel results'), plus the exact UI path (Design > Shear Wall Design > Start Design/Check). This cleanly separates it from siblings like etabs_run_design (general design) and etabs_get_wall_design (retrieving existing results).

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 gives a clear precondition chain: ETABS must be visible, and walls must already carry pier/spandrel labels assigned via etabs_assign_label. It does not, however, explicitly state when to prefer this over etabs_run_design or etabs_get_wall_design, so the alternative-selection guidance is implied rather than stated.

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