femm_gap_results

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

With no annotations, the description carries the full burden and does so substantially: it discloses the underlying FEMM calls (mo_gapintegral modes 0/1/2, mo_getallgapharmonics), how include_ac alters the result (adds 2x torque/force plus interaction terms), the units of angle, and a genuinely important gotcha—FEMM returns zeros rather than an error for an unknown boundary name. It does not state whether a prior solve is required or the read-only nature of the operation, so it falls just short of full behavioral coverage.

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?

The main purpose is front-loaded in the opening clause, and every clause carries information (output types, function names, mode codes, the zeros warning). It is dense and habitually parenthetical/run-on, which slightly hurts readability, but there is no filler or repetition.

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, no-output-schema, no-annotation tool, the description covers the returned quantities (so no output schema is needed), most parameter meanings, the required boundary type, and an error-behavior caveat. Missing details—whether a solved problem state is required and the meaning of 'session'—are minor but keep it from being fully self-sufficient.

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 compensate, and it does for 5 of 6 parameters: boundary (the target boundary), angle (deg), npts (number of angles for the CSV distribution), harmonics (count of largest Br harmonics), and include_ac (2x torque/force and interaction terms). Only 'session' is left unexplained, so the parameter semantics are largely rescued despite the empty schema.

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?

The description names a specific operation (computing air-gap/sliding-band results) on a specific resource (a periodic/antiperiodic air-gap boundary) and enumerates exactly what is returned: torque, force, stored energy, Br/Bt at an angle, a CSV distribution with stats, and harmonics. This is specific enough that an agent can immediately distinguish it from generic sibling tools like femm_line_integral or femm_point_values, and 'Magnetics only' further narrows scope.

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?

It implies a precondition—the boundary must have been created via femm_add_boundary with bc_type='periodic_air_gap'—and flags 'Magnetics only', which guides applicability. However, it never names an alternative tool or states when to prefer this over femm_line_integral/femm_block_integral for gap-region computation, so the routing guidance is only implied.

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