units.energy_convert

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds real operational context on top: case sensitivity, Decimal-string magnitude, the thermochemical definition of cal (4.184 J), and that out-of-list units raise an error. It does not discuss precision/rounding of the Decimal coefficient, which is the one remaining behavioral unknown.

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?

Four tight sentences, each earning its place: unit set, case sensitivity plus input encoding, the cal conversion factor, and the error condition. Constraints are front-loaded before edge cases.

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?

An output schema exists, and the description still names the return shape (magnitude and unit) while covering error behavior and encoding requirements. The only missing piece is routing for cases outside the supported set, where an agent must guess to fall back to units.convert.

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% with three undocumented required params, so the description carries the burden and does compensate: magnitude must be a Decimal string, from_unit/to_unit must be drawn from the case-sensitive unit list. It stops short of stating explicitly which parameter is the source versus target unit or the accepted magnitude syntax (sign/exponent form).

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 (에너지 단위) and enumerates the exact supported unit set (J, kJ, cal, kcal, eV, BTU, Wh, kWh), so an agent knows precisely the domain. It does not, however, reference the closest sibling units.convert for non-energy units, so sibling disambiguation is left implicit.

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 boundaries are implied through the supported-unit list and the explicit statement that unlisted units (MJ, international-table calorie) produce an error. That tells the agent what inputs are valid but never states when to prefer this tool over units.convert or units.pressure_convert.

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