femm_experiment_inductance

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

No annotations are provided, so the description carries the full burden. It discloses real behavior: the zero-current subtraction, the energy check W = 1/2 L I^2 for linear models, the dq-mode cross-check against FEM torque. But it omits whether the tool mutates state, whether a solve is required beforehand, what happens if circuit names are invalid, or what the return looks like.

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?

It is reasonably compact and the default mode is front-loaded, but the dq sentence is dense and underspecified, dropping a formula fragment ('psi_pm, Ld, Lq, saliency and the dq torque') without clear structure. The two modes are not visually separated, making it harder to parse than necessary.

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 6-parameter physics experiment tool with no annotations and no output schema, the description covers the core computation and the dq mode but leaves key operational details missing: required session context, precondition of an existing solution, error behavior, and the meaning of output quantities. It is adequate but not complete enough to call confidently without reading the schema.

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% and there are 6 parameters, so the schema provides only names and types. The description explains the dq nested-object structure with an example (circuits, pole_pairs, theta0_deg, id, iq) and touches on circuits and torque_groups/gap_boundary, but it never explains current, session, or the units/meaning of the free-form dq keys, leaving half the parameters undocumented.

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: computing inductance from flux linkage, with the exact formula. It reads as a physics computation tool distinct from siblings like femm_circuit_results, though it never explicitly names a sibling to differentiate from.

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?

The description implies usage through mode descriptions (default self/mutual matrix vs dq mode) and prerequisites like 'subtracting the zero-current solve' and needing torque_groups/gap_boundary for the check. But it never says when to choose this over femm_circuit_results, femm_experiment_ac_sweep, or other result tools, and gives no exclusions or preconditions like 'solution must exist'.

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