spring_check

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

With no annotations, the description carries the full burden and does well: it enumerates return fields, documents default derivation of G and allowable, discloses the 700 MPa spring-steel fallback for materials lacking UTS, and warns that shear_sf and pass scale with the allowable. It stops short of stating error behavior (e.g. what happens if both force_n and deflection_mm are given).

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?

Front-loads the purpose with the governing equations, then the return contract, then the material/override notes. Dense but every segment earns its place; the formula block is the only arguably expendable portion, and it does inform parameter meaning.

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?

No output schema exists, yet the description lists all returned keys, and it covers the highest-risk parameters (G, allowable, force/deflection). With 9 params and 0% schema coverage it is nearly complete, missing only a brief note on the geometry params and mutual-exclusivity/error handling.

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 0%, so the description must compensate, and it does: it clarifies the force_n/deflection_mm alternative, the meaning of material, and the override semantics of shear_modulus_mpa and allowable_shear_mpa (including the fallback). The remaining params (wire_dia_mm, coil_mean_dia_mm, active_coils, free_length_mm) are only implied by the formula symbols rather than explained.

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 and resource ('Rate a helical compression spring') and grounds it in named methods (Wahl) plus the equations used, so an agent knows exactly what computation this performs. It doesn't explicitly distinguish itself from the sibling add_spring (creation) tool, so sibling differentiation is left to inference.

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?

Gives one concrete calling rule ('Pass force_n OR deflection_mm') and notes that material supplies G and allowable unless overridden, which is genuine usage guidance. However, it never says when to use spring_check versus add_spring or other check tools, nor states prerequisites or exclusions.

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