femm_material_add

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

With no annotations, the description carries the full burden and does disclose non-obvious behavior: only the current physics's arguments are consumed, '*_y defaults to *_x', and supplying bh_points makes the material nonlinear so mu is ignored. It still omits side-effect context such as whether an existing material of the same name is overwritten or whether a session/document must already be open.

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-loads purpose in the first sentence, then organizes the parameter block by physics (magnetics/electrostatics/heatflow/currentflow), which is highly scannable. It is dense and slightly repetitive (qv, eps_x/eps_y, sigma appear under more than one physics), but nearly every line carries needed information.

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 26-parameter tool with no annotations and no output schema, the definition is close to self-sufficient: units, per-physics grouping, defaults, and the nonlinearity override are all present. It stops short of describing the session parameter, the required name, or failure/overwrite semantics.

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% across 26 parameters, so the description must compensate fully, and it largely does: it assigns units and meaning to nearly every argument (mu relative, h_c A/m, j MA/m^2, sigma MS/m, lam_d mm, k W/m/K, kt MJ/m^3/K) and enumerates lam_type's 0-6 codes inline. Only 'session' and 'name' go unaddressed, which is a minor gap against very strong coverage.

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+resource: 'Define a custom material for the session's physics', with the underlying API call (xi_addmaterial) named. It clearly positions itself as the custom-material creation path versus sibling readers/mutators like femm_material_get, femm_material_load, and femm_material_modify, though it never names those siblings explicitly.

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 is implied rather than stated: 'custom material' and 'for the session's physics' hint at when to use it, and 'Only the arguments of that physics are used' constrains how to call it. There is no explicit when-not guidance or routing to alternatives such as femm_material_load (library material) or femm_material_modify (edit existing).

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