plasticity_calculate_mmb_mode_i_ii_energy

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

Annotations only declare read-only/non-destructive; the description adds substantial behavioural context: required source hashes/locators, an explicitly confirmed axis mapping, a confirmed lever-weight condition, the Reeder-Crews beam-theory basis, and the returned quantities (Mode-I, Mode-II, total ERR and Mode-II fraction).

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-loaded with the core purpose and scope, then requirements, then exclusions; every sentence carries information. It is densely packed into long clauses, which slightly hurts readability but not substance.

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 an 11-parameter, no-output-schema, read-only calculation tool, the description fully covers inputs expected, preconditions, computation method, and returned values, leaving nothing essential for correct invocation unstated.

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 carry parameter meaning; it does well, naming materialProcess, interface normal/shear direction, source hashes and locators, flexural modulus, orthotropic E11/E22/G13, axes mapping, and lever weight. It leaves testProtocolHash, testMethod, testedAt and the individual specimen sub-fields (width, span, lever arm, crack length, criterion) only implicitly covered.

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 ('Calculate an exploratory mixed-mode initiation-energy partition') plus the exact inputs (MMB critical force, crack length, specimen/fixture geometry, one-material process, interface normal and shear direction). It is immediately distinguishable from the DCB Mode-I, ENF Mode-II, and cohesive-FEA siblings.

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?

Explicitly scopes what the tool is not for ('does not select initiation from raw test traces, establish ASTM D6671 conformity, infer a traction-separation law, qualify material, or authorize design/printing') and positions it against the measured-curve registry and cohesive FEA. It also states eligibility ('Only confirmed interface failures are eligible').

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