Elastica Deflection

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

Beyond the readOnlyHint annotation, the description discloses that this is a closed-form no-solver calculation, names the governing theory, states the linear-theory comparison, and warns about applicability limits. It also enumerates the full return payload, so an agent knows exactly what behavior and outputs to expect. No contradiction with annotations.

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?

The description is dense and front-loaded with the key fact, followed by formulas, validity, and return fields. It contains no filler or repeated schema information; the only reason not to give full marks is the length and technical density, though every sentence earns its place.

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 7-parameter engineering calculator with no output schema and no parameter descriptions, the text supplies the mathematical model, parameter-combination rules, valid range, and output fields. Minor gaps remain around conflicting section/E inputs and the meaning of fidelity or band_pct, but the agent has enough 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?

The schema has 0% description coverage, and this description fully compensates: it explains section choices via width_mm and height_mm or explicit i_mm4, E from youngs_gpa or material, and defines α = P·L²/(E·I), connecting load_n, length_mm, E, and I. It even notes that load is transverse to height_mm, adding physical meaning absent from the schema.

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 first sentence names the exact resource and operation: 'Exact large-deflection cantilever tip — Bisshopp–Drucker elastica' with the explicit 'NO solver' distinction. It also differentiates itself from solver-based FEM siblings by describing itself as the closed-form twin the NLGEOM CalculiX solve is gated against.

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 an explicit validity envelope ('tip slope < ~80° (α ≲ 3.5)') and an explicit escalation path: 'beyond that escalate to a follower-load fem_set_nonlinear_material solve.' It also frames the analytical result as a benchmark, telling an agent when to use this versus a nonlinear FEM solve.

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