etabs_set_mass_source

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds no behavioral context beyond vocabulary: it does not say whether calling it replaces or appends to an existing mass source, whether an unlocked model is required, or how it interacts with active load patterns — all meaningful gaps for a mutation tool.

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?

A single front-loaded sentence with zero filler; the core action comes first and the parenthetical UI anchor is a useful, compact clarifier.

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?

An output schema exists, so return values need not be explained, which helps. But for a model-mutating definition tool in a suite containing etabs_unlock_model and etabs_set_modal_case, the description omits the model-state and downstream-analysis context needed to invoke it confidently.

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 only 33% (only 'loads' has a description), so the description must compensate — and it partially does by enumerating the three concepts (self mass, added mass, load patterns) that correspond to the three parameters. However, it adds no syntax or default-behavior detail for include_self_weight / include_added_mass beyond their own names.

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 ('Set') and resource ('the default mass source') and even anchors it to the ETABS UI path (Define > Mass Source). This lets an agent distinguish it from other define/set tools, though it never names or contrasts with the most relevant sibling (etabs_set_modal_case, which consumes the mass source).

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?

No when-to-use guidance at all: no mention that this must precede modal/seismic analysis, no prerequisites (e.g., model unlock state), and no statement of when an agent should prefer this over sibling tools like etabs_define_load_patterns or etabs_set_modal_case. The agent is left to infer all usage context.

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