elastica_deflection

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

No annotations are provided, so the description carries the whole burden, and it delivers: no solver (pure closed-form), the elliptic-integral solution method, the validity range α ≲ 3.5, the escalation target, and the diagnostic outputs warnings/escalate_to/fidelity/band_pct. It also flags the physics it captures that linear theory misses (axial draw-in, over-prediction).

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?

Dense but front-loaded — purpose first, then geometry, then physics, then validity, then return shape. Every clause (formula for I, α definition, escalation threshold, output list) carries information the agent cannot get from the schema or annotations, so nothing is filler.

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 no annotations and no output schema, the description still supplies the behavioral profile, the validity envelope, the escalation route, and a full enumeration of return fields. Nothing an agent needs to select or invoke this tool correctly is missing.

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 0%, yet the description conveys the role of every parameter: width_mm+height_mm form a solid rectangle with I = b·h³/12 and load transverse to height_mm, i_mm4 is the explicit alternative, E comes from youngs_gpa or a Materials-DB `material`, load_n sets α = P·L²/(E·I), and length_mm is L. It adds the section geometry and load direction that the schema does not.

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 precise verb+resource: closed-form large-deflection cantilever tip via the Bisshopp–Drucker elastica. It explicitly distinguishes itself from the FEM siblings ("NO solver", "the closed-form twin the *NLGEOM CalculiX solve is gated against"), so an agent can separate it from fem_run / fem_set_nonlinear_material without opening any schema.

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 an explicit applicability window ("Valid for tip slope < ~80° (α ≲ 3.5)") and a concrete when-not/escalation path ("beyond that escalate to a follower-load fem_set_nonlinear_material solve"), naming the alternative tool. This is the full when/when-not/alternative triad.

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