calculate_solder_paste_volume

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real domain context beyond that (IPC-7525A basis, the 1.0~2.5 acceptance window, the two defect classes it flags), but it never describes what the result looks like or how the per-aperture findings are reported, and no output schema exists to fill that gap.

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 dense sentence with no filler; purpose, governing standard, acceptance criterion and outputs are all front-loaded. Slightly hard to parse as one run-on, but every clause carries 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 read-only calculation tool the safety side is complete via annotations, and the method and tolerance window are stated. However, the description refers to comparison 'against target joint volume' while the apertures schema exposes only ref, shape, width_mm and length_mm, leaving unexplained where the target joint volume comes from, and with no output schema there is no description of the returned per-aperture results.

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 100% with defaults documented for foil_thickness_um, target_standoff_mm and transfer_efficiency, so that is the baseline 3. The description adds no parameter-level detail, such as units or ranges for the standoff/foil inputs, beyond what the schema already states.

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 gives a specific verb (assess) and resource (per-aperture deposited solder paste volume vs. target joint volume) and anchors it to IPC-7525A transfer analysis, so the function is unmistakable. It does not explicitly name or contrast itself with the closest sibling, calculate_stencil_aperture_ratios, so it stops short of a 5.

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: the mention of an accepted ratio window (1.0 ~ 2.5) and defect flagging tells the agent this is a stencil-design validation step, but there is no explicit when-to-use statement, no prerequisite, and no named alternative among the many calculate_* siblings.

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