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 real behavior: arc direction (counter-clockwise), the valid angle range (0 < angle <= 180), and the side effect that end nodes are created as needed. It omits error handling, whether arcs join to existing geometry, and return behavior.

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?

Single dense sentence that front-loads the tuple format before the edge-case constraints, with each parenthetical earning its place. It is slightly run-on but well organized and free of filler.

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 geometry-creation tool with no annotations and no output schema, the description supplies the input format, direction, constraints, and side effect adequately. Missing only the meaning of the session parameter and any error/return expectations.

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 thoroughly explains the complex `arcs` tuple (x1,y1,x2,y2,angle_deg,maxseg_deg) including the meaning and tuning of maxseg_deg. The `session` parameter is left completely unexplained, which is the only gap.

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?

Names a specific verb (Add) and resource (arcs) and even specifies the tuple layout, so the action is unambiguous. It does not explicitly differentiate itself from siblings like femm_add_segments or femm_add_polyline, so the distinction is only implicit in the resource name.

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 gives no guidance on when to choose arcs over segments, polylines, or circles, and offers no prerequisites. The 'air gaps want <= 1' note is a parameter hint, not usage routing.

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

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

With no annotations, the description carries the full burden and does well: it discloses the magnetics-only scope of circuit/magdir/turns, that negative turns means opposite direction, that mesh_size None means automatic, and that a wrong-region label is a common bug. It does not cover error behavior or the session parameter, but the behavioral surface is largely disclosed.

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 lead sentence states the action and scope immediately, followed by a parameter glossary and a caveat sentence. Dense but front-loaded and each line carries information; only the slightly ragged line-wrapping keeps it from being maximally clean.

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 9-parameter mutation tool with no annotations and no output schema, the description supplies purpose, prerequisites, parameter semantics, and a placement pitfall. It omits the session parameter and any return/error behavior, leaving a small but real gap.

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 material, mesh_size, circuit, magdir, turns, and group, explaining defaults and semantics (e.g., '' for no circuit, integer group for selection/integrals). x/y and session are left unexplained, but x/y are self-evident coordinates, so the compensation is strong overall.

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 ('Add a block label') plus the coordinates and the 'in one call' property assignment. It is clearly distinguishable from sibling mutation tools like femm_set_block_prop (which modifies an existing label) because it is an additive creation tool.

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?

Provides context on dependencies: material must come from femm_material_load/femm_material_add or be '<No Mesh>' for a hole, circuit names come from femm_add_circuit, and it recommends checking placement with femm_geometry_summary. It gives clear preconditions but does not explicitly state when to prefer this over femm_set_block_prop.

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

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

With no annotations the description carries the full burden and delivers high-value behavioral facts: the verified requirement to place a '<No Mesh>' block label inside the gap annulus or the solver aborts with 'a region has no material assigned', that assignment resolves each point to the nearest segment/arc, and the periodic-pairing pairing rule. It omits return behavior, idempotency, and session scope.

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 text is long but deliberately structured per physics and front-loaded with the one-line purpose; the dense bc_type inventories are justified given 22 parameters and zero schema descriptions. Minor redundancy (periodic/antiperiodic repeated per physics) is a small cost.

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 22-param mutation tool with no annotations, no output schema, and 0% schema coverage, the description supplies the argument semantics, the assignment workflow, and a critical failure-mode warning. Gaps remain around arc_maxseg/session and the interaction with femm_set_segment_prop, but nothing essential to calling it correctly is missing.

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 22 parameters, so the description must compensate, and it largely does: it explains a0/a1/a2/phi, mu/sigma, c0/c1, value, flux, h/t_inf, beta/t_inf_rad, inner_angle/outer_angle, and the segments/arcs point-list semantics. Only arc_maxseg and session are left undefined.

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 ('Define a boundary condition') and adds the important qualifier that assignment is optional, which tells the agent this tool both creates and can bind the property. It is clearly distinguished from geometry/property siblings like femm_set_segment_prop and femm_add_block_label.

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?

Gives explicit conditional routing: which bc_type applies to magnetics vs electrostatics vs currentflow vs heatflow, the rule that periodic pairs need one boundary per pair assigned to both sides, and it names an alternative for open boundaries ('see femm_call(\'mi_makeABC\')'). It does not state when not to use this tool relative to other property-setting siblings.

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

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

With no annotations, the description carries the full behavioral burden and does disclose substantive traits: peak-vs-complex current interpretation, per-turn semantics for series circuits, and impedance-based splitting for parallel ones. It omits any statement of document/session prerequisites, error behavior, or what happens on re-definition, so a mutation tool's full profile is not covered.

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?

Dense but efficient: the Magnetics scope is front-loaded, followed by the current format, the series/parallel meanings, and the results pointer. Every clause adds information, though the series/parallel sentence packs several distinct concepts into one run-on.

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?

No output schema exists, and the description compensates by naming femm_circuit_results, which is genuinely useful. However, with zero annotation coverage and no mention of session/document prerequisites or the undocumented name/session parameters, it is only partially complete for a four-parameter mutation tool.

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%, so the description must compensate. It richly documents two of four parameters (current's AC/complex format, series' two modes), but says nothing about name or the session parameter that defaults to 'main'. Half the parameters are undocumented in both schema and description.

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: defines a circuit that carries current, scoped explicitly to Magnetics problems. An agent can identify it as the circuit-definition tool and distinguish it from femm_modify_circuit or femm_add_conductor, though the distinction from the modify sibling 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?

The series=True vs series=False explanation functions as real usage guidance, telling the agent which configuration matches stranded coils versus solid conductors and how current is interpreted in each. It routes the agent to femm_circuit_results for outputs, but gives no ordering/prerequisite context (open document, session) or when-not-to-use guidance.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses domain behavior (which 'fixed' values are legal in each physics mode and the units for each), but is silent on mutation semantics, duplicate-name handling, session requirements, and reversibility for what is clearly a write operation.

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 the purpose then lays out the mode/value matrix compactly in one block. Dense but each clause carries distinct information; no filler sentences.

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?

With no annotations and no output schema, the description supplies solid domain context and points to where solved results appear. It is complete enough to call correctly, though session semantics and write-side effects remain 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 compensate and largely does: it enumerates valid 'fixed' strings per physics mode and gives units for 'value' (V, C/m, K, W/m, A incl. complex at AC). Only 'name' and 'session' are left undocumented, and both are self-evident.

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 conductor property') and scopes it across the three problem types it applies to. It names sibling tools (femm_set_segment_prop, femm_circuit_results) that an agent would otherwise confuse it with, so it is distinguishable without opening a schema.

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?

Gives clear workflow context: define here, then assign with femm_set_segment_prop(conductor=name), then read results via femm_circuit_results(name). It does not state when NOT to use it (e.g. when a conductor already exists, or vs. add_boundary/add_circuit), but the positive routing is strong.

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

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

No annotations are supplied, so the description carries the full burden. It does disclose a genuinely non-obvious behavioral trait — 'Existing nodes at the same place are reused by FEMM' (effective dedup), plus units and coordinate-system constraints. It omits what is returned (node handles/indices), whether the session must be open, and any error behavior.

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?

Three short clauses, each load-bearing: format/units first, then the reuse behavior, then the alternative-tool routing. No filler and everything an agent needs is front-loaded.

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 no-annotation, no-output-schema creation tool the description is adequate but not complete: it omits the undocumented 'session' parameter and gives no hint of what the call returns (node identifiers), which an agent would need to follow up with femm_set_node_prop.

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. It documents the required 'points' parameter well (nested [[x,y]] pairs, problem units, axi semantics) but never mentions the 'session' parameter, leaving half the inputs unexplained in both schema and description.

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 ('Add nodes') and immediately pins down the input format '[[x, y], ...]' plus problem units and the axi constraint (x is r >= 0). It also distinguishes itself from nearby siblings by naming femm_draw_polygon / femm_add_segments as the usual choice, so an agent can route without opening schemas.

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 tells the agent when NOT to use it ('Usually you want femm_draw_polygon / femm_add_segments instead'), which is stronger than most siblings. The positive condition (standalone points not tied to a segment/polygon) is only implied rather than stated, so it falls just short of full when/when-not coverage.

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

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 usefully defines what `value` and `source` represent per physics module (A vs V vs T, Wb/m vs C/m vs watts), which is real behavioral context, but it says nothing about overwrite semantics, error behavior when no nodes lie near `points`, or required session state.

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 the primary action in the first sentence, then adds compact per-physics unit lines. Dense and information-bearing with minimal waste, though the tabular physics breakdown could be tightened.

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 5-parameter mutation tool with no annotations and no output schema, the description covers the two most semantically loaded parameters well but leaves `name`/`session` and error/overwrite behavior unexplained. Adequate but with clear gaps.

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%, so the description must compensate, and it does explain the meaning and units of `value` and `source` across four physics types plus what `points` triggers. However `name` and `session` are left entirely undocumented in both schema and description, leaving a notable gap.

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 clear verb+resource ('Define a nodal point property') and adds the optional assignment behavior to nearest nodes. It does not differentiate from the similar sibling femm_set_node_prop, but the purpose itself is unambiguous.

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?

No when-to-use or when-not-to-use guidance and no routing away from the sibling femm_set_node_prop, which operates on node properties and could plausibly be confused with this tool. The physics-type unit breakdown hints at context but does not tell the agent when to pick this tool.

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

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 usefully discloses two non-obvious behaviors: end nodes are auto-created, and crossing segments are split at intersections by FEMM. However, it omits the return value, coordinate units, and any session/state requirements.

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?

Two sentences with no filler, and the input-format spec is front-loaded ahead of the behavioral notes. Efficient and easy to scan, though terse.

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 geometry-mutation tool with no output schema and no annotations, the description covers the key behaviors and input format. It still omits units, the session parameter's meaning, and what is returned, so it is adequate but not complete.

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%, so the description must compensate, and it does document the accepted formats for 'segments' ('[[[x1,y1],[x2,y2]], ...]' or '[x1,y1,x2,y2] each'), which is valuable. The 'session' parameter is left entirely unexplained, so half the parameters remain 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 ('Add straight segments') with the qualifier 'straight' that distinguishes it from femm_add_arcs and the draw_* family. No sibling is named, but an agent can infer the role from the verb+resource without opening a schema.

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?

No explicit when-to-use, when-not, or alternative guidance is given. With many sibling geometry tools (femm_add_arcs, femm_add_nodes, femm_draw_polyline), the agent gets no signal about which to choose, leaving usage to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does describe the output contents thoroughly (args, return value, enums, notes, manual location), which is helpful transparency about what the tool returns. However, it does not explicitly state side effects, permissions, or that the operation is read-only, leaving some behavioral gaps.

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 description is a single front-loaded sentence that immediately states the tool's purpose, followed by a compact enumeration of returned fields. Every clause contributes information, and there is no filler or redundancy.

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?

With no output schema, the description appropriately explains the return structure, which is valuable. However, with no annotations and 0% input schema coverage, the definition leaves important invocation and selection details unclear, especially how to specify a command name and when to use this tool instead of related lookup tools.

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 the sole required parameter 'name' is undocumented in the schema. The description only says 'of one command', which hints that 'name' refers to a command identifier but does not explain expected format, case sensitivity, or examples. This is insufficient compensation for the complete lack of schema-level parameter descriptions.

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 clearly states the verb and resource: it retrieves the full catalog entry for one command. It enumerates the returned fields in detail, so the agent knows exactly what kind of information this tool provides. It does not explicitly differentiate itself from siblings like femm_api_search or femm_manual_section, which prevents a top score.

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?

There is no explicit when-to-use guidance, nor any mention of alternatives. The description implies that it is used for looking up a specific command's full entry, but it never states when to choose this over femm_api_search or femm_manual_section, leaving usage to inference.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses return fields and the non-obvious filtering rule that common commands are always included, but says nothing about the limit parameter's effect, pagination, or result ordering.

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, then the two filter vocabularies, then examples, then the follow-up call. Every clause carries information; no filler.

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 read-only search with no output schema or annotations, the description covers purpose, filters, return fields, and the downstream call. The main gap is the unexplained limit/result-count behavior.

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%, so the description must compensate. It explains the physics and phase filters and gives query examples, but leaves the limit parameter (default 15) entirely unexplained, so one of four parameters remains undocumented in both schema and prose.

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 (Search) and resource (catalog of every FEMM 5 scripting command), and explicitly names what it returns (name, signature, description). It cleanly distinguishes itself from the sibling femm_api_get, which it positions as the follow-up for full args.

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?

Gives clear context for use and an explicit workflow hand-off ('Then femm_api_get(name) for full args'), plus concrete example queries. It does not state when-not to use search (e.g., when the command name is already known), so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the full burden and reveals substantial behavior: the block-selection rule, per-physics default codes, result units (J, W, N, N m), the 'select moving part surrounded by air' caveat for stress-tensor forces, and the planar-length caveat that results are totals not per metre. It omits any mention of the session parameter or requirement that a solved problem exists.

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 action and scoping rule, then the code table. The code listing is long but each entry carries load-bearing meaning (units, selection caveats). Slightly dense but no filler sentences.

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 4-param tool with no annotations and no output schema, the description supplies enough to call it correctly, including per-physics defaults and result semantics. The unexplained session parameter and the unstated dependency on a prior solve are the only notable gaps.

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 largely does: it defines group as a list of group numbers, points as the basis for block selection, and codes as the integration quantities with an explicit magnetics code table and defaults. Only the session parameter is left unexplained.

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?

Opens with a specific verb+resource ('Integrate over blocks') and immediately explains block selection via points/group. It is distinguishable from siblings like femm_line_integral and femm_point_values by naming the underlying xo_blockintegral operation and the block-scoped selection model.

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?

Provides strong context on when to use each code (per-physics default code sets for magnetics/electrostatics/heatflow/currentflow) and how blocks are chosen (points vs group). It does not explicitly state when to prefer this over femm_line_integral or name exclusions, so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden and partially discharges it: it discloses that this creates and writes a new document, gives the default save location, and describes the return content (groups, circuits, analytic estimates). It does not say whether an existing file at `path` is overwritten, what permissions/session state are required, or how failures surface.

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 action and return value are front-loaded, followed by a dense but information-bearing per-kind enumeration. It is a long single block with no formatting aids and slight redundancy between the parenthetical save note and the path mention, but every clause carries real content.

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 four-parameter tool with no output schema and no annotations, the description is unusually complete: it covers the return shape, the default file destination, and the semantics of three of four parameters. The remaining gaps (session behavior, overwrite policy, error handling) keep it short of a 5.

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%, so the description must compensate, and it largely does: `kind` values are effectively enumerated with per-kind structure, `path` is explained including its default, and `params` is explained as builder kwargs with a concrete example. Only `session` (default 'main') is left entirely unexplained.

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 gives a specific verb and resource ('Build a validated benchmark model from scratch (new magnetics document...)') and enumerates the four supported kinds with their internal structure. It clearly distinguishes itself from generic document tools like femm_new_document by being a benchmark scaffolder that also returns groups, circuits and analytic estimates.

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: an agent can infer this is the entry point for a canned benchmark setup, and the kind list helps pick a model. However, there is no explicit when-to-use/when-not guidance and no named alternative (e.g. vs femm_new_document for a blank document or femm_experiment_* for running sweeps).

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

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

With no annotations, the description carries the full burden and delivers: it discloses catalog pre-validation, that warnings (arity/type mismatches, unknown names, pyFEMM-only helpers like mo_getb) are surfaced in `warnings`, and crucially that the call is still sent unless the name is unknown to both catalog and engine. Automatic string quoting and the non-conversion of complex values are also stated.

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 action and an example, then the validation/warning semantics, then the femm_eval pointer. The two examples and the cross-reference to femm_api_search each earn their place; no filler sentences.

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 generic passthrough tool with no output schema and no annotations, it covers invocation, validation, and warning behavior well. It does not describe what a successful call returns beyond the `warnings` field, and omits the session parameter, leaving minor gaps.

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%, so the description must compensate. It does well for `args` (positional, with two worked examples, plus quoting and complex-value rules) and `command` (a catalog command name). However, the `session` parameter (default 'main') is never mentioned, leaving one of three 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 ('Call any FEMM 5 scripting command by name with positional args') and grounds it with two concrete call examples. An agent can distinguish it from siblings like femm_eval, femm_run_script, and femm_run_lua, which are different mechanisms rather than a single named command.

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?

Gives clear context (raw command passthrough) and an explicit alternative with a condition: complex values should go through femm_eval instead, and femm_api_search is named for discovery. It stops short of stating when to prefer this over femm_run_script/femm_run_lua for multi-statement work, so it lacks full exclusion coverage.

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

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

With no annotations, the description carries the burden, and it does well: it discloses that this performs no FEMM call (no session required, side-effect free) and gives the exact return shape {name, ok, value, expected, tolerance, message}. It omits error/failure behavior, but the compute-only nature is made explicit.

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 the core purpose, then a discovery hint, then three compact illustrative examples and the return shape. Dense but every element earns its place; the examples add a little bulk over a minimal statement.

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 2-param offline compute tool with no output schema, the description supplies the return contract, the rule discovery mechanism, and concrete argument examples, leaving little an agent needs to call it correctly.

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% and the generic 'args' object is opaque, but the description compensates by naming the rule strings and showing the required args per rule (energy/flux_linkages/currents, p_input/p_losses, f_a/f_b/tolerance). This meaningfully fills the 0% coverage gap.

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 ('Run one pure physics rule on numbers you already have') and immediately scopes it with 'no FEMM call', which cleanly distinguishes it from session-driven siblings like femm_solve or femm_point_values.

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?

Tells the agent when to use it (numbers you already have, offline check) and how to discover the rules via rule='list'. It doesn't name an alternative tool or state when NOT to use it, but the offline-vs-session framing is a clear usage cue.

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

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

With no annotations, the description carries the full behavioral burden. It discloses returned quantities, units, derivation formulas, and the important caveat that inductance is valid for a circuit alone in the model with mutual effects included. It stops short of stating read-only status or session requirements, but is rich for a results-query tool.

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 description is dense but organized by physics mode and front-loads the magnetics case. Technical parentheticals and function names add density, but every clause conveys useful result semantics rather than filler.

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?

There is no output schema and no annotations, so the description must explain return values, which it does well across multiple physics modes. It still omits the session parameter and any call prerequisites, but is largely complete for a complex result-retrieval tool.

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. It clarifies that `name` refers to the circuit or conductor name, but it completely omits the `session` parameter and its default behavior, leaving one of two 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?

The description states a specific resource (circuit/conductor results) with exact quantities returned, including current, voltage, flux linkage, and derived inductance/resistance/impedance. It distinguishes itself from generic field tools by scoping to circuit and conductor properties across magnetics, electrostatics, heat, and current modes.

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 explains which physics modes produce which result types, which implies when the tool applies. However, it does not name alternative result tools such as femm_point_values, femm_block_integral, or femm_line_integral, nor does it say when to prefer this tool over them.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does not state that this is non-destructive (i.e., clears selection without deleting geometry, unlike femm_delete_selected), nor whether the operation affects the active document/session or how it behaves if nothing is selected.

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?

A single short, front-loaded sentence with no wasted words. It is arguably too terse for the value it could add, but structurally clean.

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 simple, low-risk selection-clearing tool with no output schema and one optional defaulted parameter, the description is nearly adequate. However, it omits the non-destructive distinction and any mention of the session parameter, leaving small gaps.

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?

The schema has 0% description coverage and one parameter ('session', default 'main'), which the description never mentions. Since the parameter is optional with a default, the omission is not fatal, but the description adds no meaning beyond the bare 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?

States a specific verb ('Deselect') and object ('everything in the pre-processor'), clearly the inverse of the sibling femm_select and distinct from femm_delete_selected. It does not explicitly name those siblings, but the action is unambiguous.

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?

No guidance on when to use this versus femm_select or why one would clear a selection before another operation. 'In the pre-processor' hints at context but states no prerequisites or alternatives.

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

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

With no annotations, the description carries the full burden, and it does disclose two useful behavioral facts: both pre- and post-processor documents are closed, and the engine/session survives. However, it does not say whether unsaved changes are discarded or whether the call errors when nothing is open, which matters for a destructive close.

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?

Two short sentences with zero waste. The scope of the close is front-loaded, and the sequencing note follows immediately; every clause earns its place.

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 simple one-parameter tool with no output schema and no annotations, the description covers what is closed and what to do next, which is most of what an agent needs. It is still incomplete on the session parameter and on the fate of unsaved work, the two gaps most likely to cause a wrong invocation.

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 the description never mentions the 'session' parameter at all. The highest-value information here — that closing applies to a named session defaulting to 'main' — is left entirely to the raw schema, so the description fails to compensate for the coverage gap.

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 gives a specific verb and resource: closing the 'current pre-processor document and its post-processor (if any)'. It implicitly distinguishes itself from femm_session_close by noting 'the engine keeps running', making the scope of the close operation unambiguous. It stops just short of naming the sibling it differs from 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?

It gives clear forward guidance: 'call femm_new_document or femm_open next', naming both alternatives for the follow-up step. There is no explicit when-not condition (e.g. unsaved-changes behavior), but the sequencing context is unusually concrete for a close tool.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose useful traits: rows are matched on the first column, and differences beyond `rtol` are flagged. However, it says nothing about side effects, session/auth requirements, or what the comparison returns, leaving real gaps relative to a no-annotation baseline.

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?

Three sentences, front-loaded with the core action, then matching semantics, then usage examples. Some density in the parenthetical '(rows matched on the first column, e.g. angle)', but every clause carries information and nothing is wasted.

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?

There is no output schema, so the description should ideally convey the shape of the comparison result; it only notes that out-of-tolerance differences are flagged. Combined with two undescribed params, it is adequate for calling the tool but incomplete about what comes back.

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%, so the description must compensate, and it does well for the three substantive params: `a`/`b` are explained as paths to experiment .json files or raw JSON text, and `rtol` is explained as the difference tolerance. `label_a`/`label_b` are not described, but they are self-evident labels with defaults, making this a strong compensation.

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 (A/B comparison) and resource (two experiment results), and goes further to specify exactly what is compared: every numeric summary value and every common numeric column. No sibling tool overlaps this function, so an agent can identify it unambiguously.

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 says when to use it: 'to compare mesh refinements, the rotate vs air-gap-element methods, or two designs.' This is clear context, but it does not name a competing tool or state when-not to use it (e.g., comparing a single result or non-experiment data).

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

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 usefully discloses that offsets are cumulative ('a further' shift/rotation) and that rotation is about `about` (default origin), but it says nothing about permissions, whether the original selection is preserved or altered, or whether new entities become the active selection.

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?

Two sentences, front-loaded with the core operation and followed by a compact worked example. No filler, though the example is dense with inline code that could be slightly tighter.

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 7-parameter, no-annotation, no-output-schema tool this is close to adequate: the geometry parameters and a canonical workflow are covered. Gaps remain around `session` and the fate of the original selection, but the essential calling information is present.

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 the geometric core: copies, dx, dy, rotate_deg, about, and entities are all given meaning (including cumulative semantics and the default origin). The `session` parameter is left entirely unaddressed, preventing a 5.

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 (copy) and resource (the selection), and clarifies that copies are cumulative ('each shifted by a further (dx, dy)'). This distinguishes it cleanly from femm_move_selected, femm_mirror_selected, and femm_scale_selected in the sibling list.

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?

Provides a concrete workflow: draw one slot, then femm_select(kind='group') followed by femm_copy_selected(rotate_deg=360/Q, copies=Q-1, entities='group'). This tells the agent the prerequisite (a selection / group) and the intended pattern, though it never states when *not* to use it or contrasts it with mirror/scale alternatives.

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

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

With no annotations, the description carries the full burden and does well: it discloses the hidden side effect that the model is saved first, that no element count is returned by FEMM 5, and how to interpret meshing errors (open regions, overlapping lines). It omits what the tool actually returns on success.

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 action and scope in the first clause; the parenthetical about solve timing is mild padding but the rest earns its place. No redundant restatement of the name.

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 no-annotation, no-output-schema, one-param tool, the description covers the important behavioral traits (implicit save, no return count, error interpretation). It is only short on session semantics and what a successful call actually returns.

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?

The single 'session' parameter has 0% schema description coverage, and the description never mentions sessions or how to target a non-default one. The description adds no meaning beyond the bare schema property name.

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 ('Mesh the model') and pins the scope precisely with 'without solving', naming the underlying API call (xi_createmesh) and the goal ('check that meshing succeeds'). This clearly separates it from femm_solve and femm_smartmesh in the sibling list.

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?

Explains the use case (verify meshing succeeds before/instead of solving) and implicitly routes the agent to femm_solve when element counts or results are actually wanted. It doesn't state exclusions as explicitly as 'use X instead' but the when-to-use context is clear.

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

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

With no annotations, the description carries the full burden. It usefully discloses one non-obvious destructive side effect (deleting nodes cascades to attached segments/arcs), but says nothing about reversibility/undo, permissions, or how 'session' affects scope. One good disclosure against several unstated traits.

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?

Two tight sentences, front-loaded with the action and followed by the parameter vocabulary. Every clause earns its place; the parenthetical caveat is well placed.

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 destructive operation with no annotations and no output schema, an agent still lacks reversibility, prerequisite, and 'session' scoping information. The cascade note partially covers the risk profile but leaves meaningful gaps.

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%, so the description must compensate. It does document the accepted values for 'kind' (all | nodes | segments | arcs | labels) plus the node-cascade behavior, which is real added value; however 'session' is left entirely unexplained and there is no enum in the 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?

States a specific verb (Delete) and resource (the current selection), which is distinct from siblings like femm_clear_selected (deselection) and femm_move_selected/copy_selected. It does not explicitly contrast itself with those siblings, but the verb+object is unambiguous.

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?

Implies a selection must exist first ('the current selection'), but never states when to prefer this over femm_clear_selected or other selection operations, nor any prerequisites (e.g., an open document/session). Usage is only inferable.

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

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

With no annotations, the description carries the full burden. It usefully discloses the internal decomposition (four 90-degree arcs, node placement at cardinal angles), which is real behavioral context. However it says nothing about permissions, undo/reversibility, selection state effects, or how the result interacts with existing geometry — notable gaps for a mutation tool with zero annotation 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?

Two tight sentences with the core construction detail front-loaded and the alternative routing last. Dense but every sentence earns its place; the parenthetical node angles are arguably more than needed but genuinely informative.

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 geometry-drawing tool with no output schema and no annotations, the definition supplies the essentials: what is created, how it is discretised, and when to prefer a sibling. The single unexplained 'session' parameter is a minor residual gap.

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%, so the description must compensate, and it largely does: r is the radius, cx/cy the centre, and maxseg is defined as 'arc discretisation in degrees'. Only the session parameter (default 'main') is left undocumented in both schema and description.

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?

Specific verb (draw) plus resource (circle) with precise construction semantics: 'Full circle of radius r around (cx, cy) as four 90-degree arcs (nodes at 0/90/180/270 deg).' It distinguishes itself from the sibling femm_add_arcs, so an agent can choose correctly without opening schemas.

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?

Gives an explicit alternative with its condition: 'For a half circle in axi models, use femm_add_arcs.' That is clear routing, though it covers only one exclusion and says nothing about when a circle should be drawn vs a rectangle or polygon approximation.

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

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

With no annotations, the description carries the full burden. It discloses genuinely useful behavior beyond the schema: that nodes and segments are created, closure is applied by default, and the return is the vertex centroid with a convexity caveat for block labels. It omits session/permission context and whether existing geometry is affected.

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?

Two tight sentences, front-loaded with the most important detail (the points structure) and no filler. Slightly dense with the parenthetical caveat but nothing wasteful.

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 three-parameter drawing tool with no output schema and no annotations, the description covers the input format, default closure, and return value, which is adequate. It still leaves session handling and any side effects on existing document geometry unaddressed.

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. It usefully explains the points format ([[x, y], ...]) and ties 'closed back to the first point by default' to the closed parameter, but leaves the session parameter entirely unexplained.

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 (draw) and resource (polygon) plus the concrete effect of creating nodes + segments. It distinguishes itself from femm_draw_rectangle/circle by being point-driven, but never explicitly contrasts with femm_draw_polyline or femm_add_segments, so sibling differentiation is only implied.

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?

No statement of when to use this versus the many alternatives (femm_draw_polyline, femm_draw_rectangle, femm_add_nodes/add_segments). The only usable cue is the implicit 'closed by default' behavior, which is not framed as guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond shape. It does not say whether the geometry is committed immediately, whether it replaces or appends to existing document content, what session scoping does, or whether the operation is reversible. For a document-mutating geometry call with zero annotation coverage this is a real gap.

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?

Two short sentences, front-loaded with the shape definition, with zero filler. '(not closed)' is mildly redundant with 'open chain of segments', a tiny bit of duplication that keeps it just short of perfect.

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?

No output schema and no annotations mean the description must stand alone, yet it omits the session parameter entirely, says nothing about return values, and gives no constraints such as minimum points or units. For a geometry-creating tool in a large CAD-style toolset, this leaves the agent under-informed about correct invocation.

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. It does add meaning for 'points' by showing the [[x, y], ...] nesting, clarifying that items are coordinate pairs in a specific order that the untyped nested arrays do not convey. But the 'session' parameter is documented nowhere, and no coordinate units, ranges, or minimum-point-count constraints are given.

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 (draw) and resource (polyline, defined inline as an 'open chain of segments'), and explicitly distinguishes it from the sibling femm_draw_polygon by noting it is the non-closed case. An agent can tell it apart from femm_polygon and femm_add_segments without opening a schema.

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 equivalence note 'Same as femm_draw_polygon(closed=False)' implicitly tells the agent these two are interchangeable, which is useful routing information. However, there is no explicit guidance on when to prefer a polyline over separate segments (femm_add_segments) or when drawing vs. adding geometry, so usage stays implied.

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

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

No annotations are provided, so the description carries the full burden, but it does disclose a meaningful side effect: the tool creates exactly 4 nodes and 4 segments. It omits units, whether an open document/session is required, and what happens with degenerate coordinates.

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?

Two tight sentences with the geometry definition front-loaded and the follow-up action second. Nothing is redundant.

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 simple 5-parameter drawing tool with no output schema and no annotations, the description covers geometry, side effects, and the next workflow step. It could still note coordinate units and session/document prerequisites.

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. It clarifies that (x1,y1) and (x2,y2) are opposite corners, which the bare titles X1/X2/Y1/Y2 do not convey, but it never mentions the optional 'session' parameter (default 'main').

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 ('Axis-aligned rectangle with opposite corners (x1,y1), (x2,y2)') and adds the resulting geometry ('4 nodes + 4 segments'), which distinguishes it from siblings like femm_draw_polygon or femm_draw_polyline that could also enclose a rectangle. It stops short of explicitly naming which sibling to use instead.

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 second sentence gives a real workflow cue: add a block label inside it afterwards via femm_add_block_label. However, there is no when-not guidance and no contrast against the other draw_* tools, so usage is implied rather than specified.

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

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

With no annotations, the description carries the burden and does reasonably well: it declares the calling convention (no name lists formulas), the unit system, and the idealisation-error caveat. It stops short of describing validation/error behavior for unknown formula names, but for a pure read-only computation this is adequate.

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 units and the no-name behavior, followed by concrete examples, with no filler sentences. It is dense but each clause adds either a formula name, an argument key, or a usage caveat.

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 parameterised estimator with no output schema and 0% schema description coverage, the description supplies the formula inventory, argument examples, and the self-documenting no-name mode. The main residual gap is that per-formula argument semantics must be discovered by an extra call, but the tool provides that path explicitly.

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%, so the description must compensate, and it does: three fully worked call examples show the exact shape of the args object and its keys (turns, current, gap, mu_r, pole_pairs, psi_d, etc.), and the formula list enumerates valid name values. It does not document every argument of every formula, but it points to the no-name listing mode for the full set.

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 states a specific verb and resource: evaluate analytic reference formulas in SI units to sanity-check FEMM results. The concrete examples (ccore_gap_b, dq_torque, skin_depth) and the formula list make the tool's function unmistakable and distinguish it from solver/measurement siblings like femm_solve and femm_point_values.

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 explicitly frames the use case ('Compare FEMM results to these within the idealisation error') and explains the no-name listing mode, giving clear when-to-use context. It does not name alternative siblings to prefer for other tasks, but for this standalone estimator the guidance is solid.

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

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

No annotations are present, so the description carries the full burden and does well: it discloses the return convention ('tab-separated reply parsed to numbers/lists'), that statements yield null while expressions yield values, the one-line constraint, and that variables persist per session. Missing only error/failure behavior and any auth or side-effect notes.

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 action, then constraints, then concrete examples. Every sentence carries information; the worked examples ('mo_getpointvalues(0,0)[1]') are genuinely useful rather than filler.

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?

No output schema exists, and the description covers return shape, statement-vs-expression semantics, and the session persistence model, so an agent can call it correctly. The main residual gap is the 'session' parameter's semantics, which neither schema nor description explains.

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% for two parameters. The description implicitly clarifies 'expression' (one line, newline rejected) but never explains the 'session' parameter, its meaning, its default, or how sessions relate across calls beyond 'variables persist between calls in the same session.' Partial compensation for a real coverage gap.

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?

Specific verb+resource: 'Evaluate ONE LINE of MicroPython inside FEMM and return its value.' It distinguishes itself from siblings both by language ('MicroPython' vs the Lua sibling) and by naming femm_run_script as the multi-line alternative.

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?

Explicit when-not guidance: 'A newline is rejected: for multi-line code use femm_run_script.' This routes the agent cleanly. It does not, however, address the other plausible alternatives (femm_call, femm_run_lua, femm_api_get), so the routing picture is not fully closed.

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

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

With no annotations and no output schema, the description carries the full burden and does disclose the shape of results: name, path, size, and a header containing problem type, units, frequency, depth for models. It's implicitly a safe read operation. It doesn't state ordering or result-count behavior, but the behavioral profile is otherwise clear.

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?

Two tight sentences: the first front-loads what is listed and what comes back, the second covers filtering and the next action. No filler, no repetition of the tool name.

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 two-optional-parameter listing tool with no output schema, the description covers inputs, return fields, and the follow-up call. Minor omissions (ordering, whether an empty query returns everything) are not enough to prevent correct invocation.

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: `query` is defined as a substring filter and `extension` is illustrated with concrete values ('.fem', '.py', '.lua', ...), which is exactly what the bare schema lacks. It stops short of stating case-sensitivity or whether filters combine as AND, but the semantics are usable.

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 the specific resource (example models and scripts shipped with FEMM 5, in examples/ and pyfemm/examples/) and enumerates the returned fields (name, path, size, header details for models). An agent can immediately tell this is a read-only enumeration of bundled sample content, distinct from document/file tools like femm_file_summary or femm_open.

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 gives concrete filtering guidance ('Filter by substring query and/or extension') and routes the agent onward with 'Open one with femm_open.' There are no explicit exclusions or when-not conditions, but the intended workflow (list, then open) is unambiguous.

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

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

With no annotations, the description must carry the behavioral burden, and it does disclose real side-effect semantics: other probdef settings are kept and the original frequency is restored after the sweep, and `current` overrides every swept circuit's current. It omits runtime/cost expectations for a multi-frequency solve, but the state-restoration disclosure is genuinely useful context beyond a bare read/write hint.

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 formula-level output description, then prerequisites. Dense but efficient; the arrow notation is terse rather than wasteful, though the invariant-check sentence could be trimmed.

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?

No output schema or annotations exist, and the description supplies the return contents (Z, R, L, losses) plus a verification invariant, preconditions, and state-restoration behavior. Missing `session` semantics keeps it short of fully complete for a 4-parameter experiment tool.

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%, so the description must compensate. It does explain `current` (overrides all swept circuits' current) and implies `circuits`/`frequencies` behavior via 'swept circuit', but `session` is never mentioned and `frequencies`/`circuits` syntax and defaults are left 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?

The description names a specific operation (time-harmonic frequency sweep in Hz) and enumerates exactly what it computes (Z = V/I, R(f), L(f), and total/resistive/hysteresis losses across blocks). This clearly separates it from sibling experiment tools like femm_experiment_inductance or femm_experiment_backemf.

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 states concrete preconditions — conductors must have conductivity and the mesh must resolve the skin depth, pointing at femm_estimate skin_depth — which tells the agent when the tool can be called. It does not explicitly contrast itself with the other femm_experiment_* siblings, so routing is only partly addressed.

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

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

With no annotations, the description carries the full burden, and it does disclose a real side effect ('Currents are zeroed and restored') plus the spectral-derivative method. However it omits key behavioral facts for a solver experiment: whether an FEMM solve is required per step, expected runtime/cost, and any state preconditions.

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 a single dense paragraph but front-loads the purpose (open-circuit back-EMF) before the mechanics. Every clause carries information (formula, derived outputs, side effect, optional comparison), with little filler.

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 10-parameter experiment tool with no annotations, no output schema, and 0% schema description coverage, the description is only partially sufficient. It documents the computation and outputs but leaves the required rotate_groups and several parameters unexplained, which an agent needs to call it correctly.

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% across 10 parameters, so the description must compensate and only partially does: it clarifies circuits (default all), steps (sample count), pole_pairs (period formula), and psi_estimate (analytic comparison). The required rotate_groups is never explained, and rpm, center, method, session, and gap_boundary are entirely 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?

The description names a specific verb+resource: computing open-circuit back-EMF from flux linkage of each circuit over one electrical period. It is technically precise and clearly distinct in subject from the other experiment siblings (cogging, inductance, ac_sweep), though it does not explicitly name how it differs from them.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The only usage hint is that supplying psi_estimate triggers an analytic comparison; nothing tells the agent when this experiment is the right choice versus other experiment tools.

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

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

With no annotations, the description carries the burden and does well: it discloses that it runs a solve (mutating solution state), that it flags demagnetisation risk via the min B_m < min_fraction * Br condition, and that magdir-formula labels are skipped. It omits session scoping and error behavior, but the key behavioral traits are surfaced.

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?

Three information-dense sentences, front-loaded with the resource and outputs. No filler words; the skip rule is placed last where it belongs. Slightly jargon-heavy (Pc, B_m/Br) but each clause earns its place.

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?

With no output schema and no annotations, the description usefully enumerates what is returned per magnet block (mean/min B_m, H_m, Pc, B_m/Br) and the demagnetisation flag. It is nearly complete, lacking only session semantics and any note on failure when no magnet labels or solution exist.

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. It explains min_fraction precisely through the flagging inequality (min B_m < min_fraction * Br), which is meaningful. The 'session' parameter is left entirely undocumented, so half the parameters remain unexplained.

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 specific verbs and resource: it solves, then per magnet block label reports B_m, H_m, permeance coefficient Pc, and B_m/Br, plus demagnetisation flagging. This is highly specific and clearly distinguishable from sibling analysis tools like femm_block_integral or other experiments.

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?

Implied usage is clear from 'Permanent-magnet operating points', and the note that it solves first signals the precondition. However, there is no explicit when-to-use/when-not guidance or named alternative (e.g., versus femm_block_integral or another experiment), leaving the agent to infer the selection.

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

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

With no annotations, the description carries the full burden and does well: it discloses the side effect that all circuit currents are zeroed and then restored, and lists self-checks (zero mean, periodic end points, WST vs virtual work). It omits return format, session requirements, and runtime/cost expectations.

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?

Dense but front-loaded, with the core operation stated first and details following. Every clause carries technical content, though the heavy parenthetical and backtick notation makes it terse for an agent to parse quickly.

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 10-parameter simulation experiment with no annotations and no output schema, the description gives useful domain context but leaves key gaps: required rotate_groups/slots semantics, session handling, and what the tool returns are all unexplained.

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 10 parameters, so the description must compensate and only partially does: it defines periods, steps (samples incl. end point), and poles (2p). Required parameters slots and rotate_groups, plus method, center, session, gap_boundary, and torque_groups, remain 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 physical quantity computed (cogging torque with all circuit currents forced to 0) over a defined sweep, which is a clear verb+resource. It also distinguishes itself from femm_experiment_torque_vs_angle by noting the shared rotor options, implying a different measurement mode, though it never says so outright.

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 only implied: an agent can infer this tool is for cogging torque specifically while torque_vs_angle is for driven torque, but the description only references the sibling to borrow parameter semantics, not to route the agent. No explicit when-to-use or when-not-to-use guidance is given.

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

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

With annotations absent, the description carries the entire behavioral burden and does so well: it discloses side effects (geometry is moved back at the end, model left solved at the start position), the default for force_groups, a built-in correctness check (WST force vs virtual work dW'/ds), and the returned row layout plus csv/json/png artifact paths.

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 semantics and organized into purpose, applicability, prerequisites, example, and return shape. Dense but virtually every sentence adds information; the example and the return-row enumeration are the only slightly expensive parts.

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 complex multi-parameter experiment tool with no output schema, the description supplies the sweep semantics, prerequisite setup, side-effect behavior, a worked example, and the exact return columns/artifacts. An agent has everything needed to invoke it correctly.

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%, so the description must define parameters, and it covers the important ones: groups, dx/dy as per-step problem-unit displacement, steps (implied by the 9-step example), and the force_groups default. Only `session` and `start_offset` go unexplained, which is a minor gap given how much else is specified.

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: sweep the parts in `groups` by (dx, dy) per step, re-solve, and record WST force, coenergy, and flux linkage. This is clearly distinguishable from sibling experiment tools such as femm_experiment_torque_vs_angle or femm_experiment_cogging without opening any schema.

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?

Gives concrete application context ('actuators, plungers, coilguns') and hard prerequisites (moving parts must be surrounded by air and carry their own group number via femm_set_group; axisymmetric dy moves along z). It does not explicitly name which sibling experiment tool to prefer when the sweep axis differs, so it stops short of full alternative routing.

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

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.

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

With no annotations, the description carries the full load and does well: it discloses that every case re-opens the same saved base model (so cases are independent, no state carryover), runs its commands, solves, and collects outputs, and it restricts case commands to preprocessor prefixes mi_/ei_/hi_/ci_. No disclosure of failure modes, runtime cost, or concurrency.

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 the purpose in one sentence, then gives dense, example-driven detail for cases/template/outputs. Every clause carries information given the empty schema, though the output-kind enumeration is run together and could be formatted more readably.

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 nested-parameter sweep tool with no annotations, no output schema, and 0% schema description coverage, the description covers cases, template, and output kinds well but leaves the 'session' parameter and the identity/loading of the 'saved base model' unexplained, which an agent needs to call it correctly.

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% and the nested cases/outputs are untyped objects, so the description must compensate — and it does, documenting case keys (name/params/commands), the template placeholders like {dx}, and the six output kinds with their fields. The 'session' parameter is never explained, keeping this below a 5.

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 ('Generic parametric study') and describes the per-case flow: re-open base model, apply setup, solve, collect outputs. The word 'Generic' implicitly separates it from the specialized siblings (femm_experiment_cogging, _backemf, _inductance), but no sibling is named 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 by 'Generic parametric study' versus the named specialized experiment tools, and 'preprocessor commands only: mi_/ei_/hi_/ci_' scopes what a case may contain. However there is no explicit statement of when to prefer this over femm_experiment_force_vs_position or the other experiment_* tools.

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

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 well: it discloses the torque extraction mechanism per method (WST block integral vs mo_gapintegral), that re-meshing occurs in 'rotate' but not 'age', the required air layer/boundary topology, and the drive model with its mean-torque sanity check. It omits whether model geometry is restored after rotation, session-scoped effects, and cost/performance behavior, so it is not exhaustive.

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?

Purpose is front-loaded in the first line and every subsequent clause carries real technical payload with no filler. It is dense and unbulleted, mixing method mechanics and the drive dict into long sentences, which slightly hurts scannability for an 11-parameter tool.

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 complex, 11-parameter experiment with no annotations and no output schema, the description covers inputs and physics but says nothing about what it returns (torque series, angles, mean-torque check results) or how results are surfaced. That is a meaningful gap when no output schema exists to fill it.

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% across 11 params, so the description must compensate, and it does for the non-obvious ones: method, rotate_groups, center (default [0,0]), torque_groups (defaults to rotate_groups plus exclusion advice), gap_boundary, and drive (with a full example dict and theta_e formula). start/stop/steps/angles/session are left unaddressed, though 'end point included' partially documents the angle range.

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 opening line states a precise verb+resource: computes rotor torque versus mechanical angle. It is self-evidently distinct from the other femm_experiment_* siblings (cogging, backemf, inductance), but it never names or routes against them, so it stops short of explicit sibling differentiation.

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 gives conditional prerequisites that imply method selection ('rotate' needs an air layer split by a circle in the gap; 'age' needs a Periodic Air Gap boundary named gap_boundary), and warns to exclude a rotor-side air layer from torque_groups. However it never states when to prefer one method over the other, nor when to use this experiment instead of the sibling experiment tools.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose that this writes the *current* geometry (not selected entities) to a file on disk, which is useful. But it says nothing about overwriting an existing file, failure behavior, or session/permission requirements for a write operation.

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?

A single short sentence with the action front-loaded and zero filler. It is appropriately sized for what it chooses to convey, even though it omits detail elsewhere.

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 file-writing tool with no annotations, no output schema, and two undocumented parameters, this description is too thin. It omits path semantics (relative vs absolute), overwrite behavior, and session handling — all of which an agent needs to invoke it correctly.

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 not. The destination file implied by 'to a DXF file' loosely maps to the required 'path', but the 'session' parameter (default 'main') is never mentioned or explained, so an agent cannot tell whether it matters here.

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: writes the current geometry to a DXF file. This clearly separates it from femm_import_dxf (opposite direction) and from femm_save (native format), even though it names no sibling explicitly. The parenthetical 'xi_savedxf' is internal jargon rather than added clarity.

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?

No guidance on when to export to DXF versus using femm_save, femm_save_bitmap, or femm_export_pyfemm_script. No prerequisites (open document, active session) are stated. The only hint is the reference to the underlying 'xi_savedxf' call.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses a lossy transformation ('femm_eval expressions that are not plain calls are kept as comments') and the default output location, which is real value beyond the schema. It does not state overwrite behavior for an existing file at the default path, error conditions, or what the generated script omits (e.g. measured results), which are the risks an agent needs to know about a file-writing tool.

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?

Three sentences, front-loaded with the core action, then the default path, then the edge case. The inline pyFEMM snippet is dense but earns its place by showing the emitted form. Little waste overall.

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 3-parameter, no-annotation, no-output-schema tool with 0% schema coverage, the description is minimally adequate: it explains the artifact and the default destination but omits headless semantics, overwrite behavior, and any hint of the return/confirmation shape. An agent could call it correctly but not predict its side effects fully.

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. It partly does: the default path template '<work_dir>/scripts/<session>_pyfemm.py' explains the role of both path and session. However, the 'headless' parameter is never mentioned, and it is the least self-explanatory of the three for an export tool, so roughly a third of the parameters remain 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?

The description states a specific verb and artifact: write the session journal as a standalone pyFEMM script with a sample of the emitted code. That is unambiguous and clearly distinct from femm_export_dxf or the generic femm_run_script/femm_run_lua, but no sibling is named, so differentiation 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?

The purpose clause 'so the user can re-run the whole model without the agent' implies the use case (handing a reproducible model to a user), but there is no explicit when-to-use statement, no exclusion, and no comparison against siblings such as femm_journal, femm_run_script, or femm_save that an agent might otherwise choose.

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

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

With no annotations, the description carries the full burden. It usefully discloses the filtering behaviour of `query` (returns only sections that mention it) and names the backing file, but says nothing about what a null query returns, output format, or any auth/rate constraints.

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 the resource identity, then the query behaviour, then the actionable advice. Three compact sentences with no filler; structure is sound.

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?

No output schema and no annotations, with an undocumented parameter. The description covers what the tool is and how query filters, but omits the unfiltered-query behaviour and the shape of the returned facts, so an agent is not fully equipped.

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% and the single `query` parameter has no schema description, so the description must compensate. It does explain that query acts as a text match returning only mentioning sections, but leaves the null/default behaviour (likely 'all sections') ambiguous.

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 resource — a curated knowledge base of verified FEMM 5 behaviour (command quirks, units, headless support, renamed materials) — which is clearly distinct from procedural siblings like femm_api_search or femm_manual_section. However, no explicit verb is used, and it does not directly name or route against those closest 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?

Offers one usage cue, 'Read this before trusting FEMM 4.2 habits', which implies when it matters. It does not state when to prefer it over the adjacent reference tools (femm_manual_section, femm_api_search, femm_examples_list), leaving the boundary implicit.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it does substantial work: data source (bulk arrays), a performance trait (fast, no file), and a concrete default (threshold 1.6 T). It omits prerequisite/error behavior (e.g., whether a solution must exist first), so it is not exhaustive.

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 the core purpose in the first clause, then layers in return values and parameter syntax with no filler sentences. Dense notation ('|B| min/max/mean/rms/p95') is efficient, though the single long paragraph is slightly heavy.

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?

With no output schema and no annotations, the description must cover both intent and outputs, and it names the exact returned statistics and the saturation metric. The main gap is that it never states the execution prerequisite (a solved mesh/session) for a results tool.

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%, so the description must compensate, and it does for two of three parameters: 'region' syntax ('all' or 'group:N[,M]') and 'threshold' (default 1.6 T, saturation cutoff). 'session' is left unexplained, which keeps it from a 5.

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 computation (area-weighted field statistics over the mesh) and a specific data source ('from the bulk arrays (fast, no file)'), which distinguishes it from file-based or integral siblings such as femm_block_integral and femm_point_values. The agent knows exactly what this produces.

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?

Gives clear context for use: the 'fast, no file' note signals when to prefer it, and it explains how to obtain per-material stats via femm_add_block_label(group=N). It stops short of naming explicit alternatives to avoid or stating prerequisites (e.g., a solved mesh).

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

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

With no annotations, the description carries the full burden and does well: it discloses a real side effect (arrays=True writes <stem>_mesh.npz next to the file), which an agent must know before invoking. It omits whether the operation is read-only or what happens on unparseable files, but the key behavioral trait is surfaced.

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?

Two sentences, front-loaded with the core action and file scope, then the return contents, then the conditional side effect. No clause is redundant.

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?

There is no output schema, so the description must describe returns itself, and it does so exhaustively (problem definition, materials with flags, boundaries, circuits, groups, counts, bounding box, magnets). Nothing an agent needs before calling is missing.

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%, so the description must compensate. It fully explains the 'arrays' flag and its npz side effect, and the extension list clarifies what 'path' may point to. Path format details (relative vs absolute) are left unstated.

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 (parse) and resource (FEMM text files) and immediately distinguishes itself from engine-dependent siblings by noting it is 'offline (no engine)'. The enumerated accepted extensions make the scope unambiguous.

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 phrase 'offline (no engine)' signals the correct context of use versus session-based siblings like femm_open or femm_load_solution. It does not, however, name any alternative explicitly or state when not to use it, so it stops short of explicit routing.

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

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.

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

With no annotations, the description carries the full burden and does well: it discloses a non-obvious side effect (the tool SAVES the model to disk, to its current path or <work_dir>/model.<ext>) and explains why (FEMM 5 has no pre-processor count getters). That the 'summary' operation writes to disk is exactly the kind of behavior an agent must know. It does not mention error/permission behavior, keeping it at 4.

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?

Three front-loaded sentences: outputs first, then the mechanism/caveat, then the intended use. The enumeration of counted entities is dense but justified as the tool's output contract. No padding.

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?

With no output schema and no annotations, the description is responsible for return content and behavior, and it covers both: what gets counted and the save side effect. It leaves the exact return format/structure unspecified, which is the only notable gap.

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?

The single 'session' parameter has 0% schema description coverage, and the description never mentions it. The value (which session to summarize, defaulting to 'main') is reasonably guessable from the name and sibling conventions, but the description does nothing to compensate for the schema gap.

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 (counts) and a concrete resource set (nodes, segments, arcs, block labels, materials, boundaries, circuits/conductors, bounding box), which an agent can distinguish from siblings like femm_problem_info or femm_file_summary without opening any schema.

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?

'Use it to sanity-check a model before meshing' gives a clear usage context and implicitly positions it relative to the meshing/solve siblings. It stops short of naming a specific alternative or stating when not to use it, so it falls just short of 5.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it enumerates every available check, the physical identity each one validates (W = W', 1/2 Re(V conj I) = losses, torque reaction balance), and the conditions under which checks apply. It stops short of stating side-effect/read-only behavior or cost, but the 'judge a loaded solution' framing makes the read nature clear.

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 description is front-loaded with a one-line purpose, then a dense parenthesized enumeration of checks and a trailing return-shape clause. Every clause carries real information, though the middle block is unabridged and could be trimmed slightly without loss.

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 8-parameter tool with no annotations and no output schema, the description is nearly self-sufficient: it names each check, its tolerance logic, the group-based parameters it depends on, and the exact return structure. Missing only the `session` parameter's role and the valid `checks` values.

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 largely does: it defines `checks` as a subset selector, `b_limit` in tesla, `flux_lines` as two cuts [[p1,p2],[p3,p4]], and the rotor/stator/force/reaction group semantics for torque and force checks. Only `session` and the exact accepted check-name strings are left unexplained.

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 opening sentence gives a specific verb and resource: 'Judge whether the loaded magnetics solution is physically sane.' That is clearly distinct from siblings like femm_selftest, femm_check_rule, femm_status, and femm_field_stats, which measure different things. An agent can route to this tool on purpose alone.

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 states the prerequisite explicitly ('Needs femm_solve first') and explains that the run can be narrowed via `checks`. It does not, however, contrast this tool against the other validation-oriented siblings such as femm_check_rule or femm_selftest, so the agent gets context but no explicit exclusions.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that `tolerance` merges nearby nodes in problem units and that None falls back to FEMM's default, but it does not say whether the import appends to or replaces existing geometry, nor any permission/session requirements.

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?

Three tightly written sentences with the purpose front-loaded, followed by parameter semantics and the follow-up workflow. No filler; every clause earns its place.

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?

Given no annotations, no output schema, and 0% schema coverage, the description covers purpose, the tricky parameter, and the workflow, but omits whether existing geometry is affected and any session/document preconditions for an import operation.

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%, so the description must compensate. It explains the non-obvious `tolerance` parameter well (merge distance in problem units, None for default), but leaves `path` and `session` undocumented, so coverage is only partial.

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 ('Import a DXF drawing into the current model'), names the underlying FEMM call (xi_readdxf), and implicitly distinguishes itself from the sibling femm_export_dxf. An agent can immediately tell what this tool does.

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?

Provides a concrete post-import workflow: check with femm_geometry_summary, then add block labels, which routes the agent to the right follow-up siblings. It gives clear context but no explicit when-not-to-use or prerequisites (e.g., whether a document/session must be open first).

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

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

With no annotations the description carries the full burden and does well: it discloses the '#! ' prefix for refused commands, that internal pings are filtered, that results are capped by limit, and that save writes a replayable script to <work_dir>/scripts/journal.py runnable via femm_run_script. It stops short of stating the permission/read-only profile or response shape beyond the line-list format.

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 the core identity before the side-effect and sibling note. Dense and largely waste-free, though the parenthetical about the script path makes one sentence run long.

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?

With no annotations and no output schema, the description adequately covers return content, error formatting, filtering, and the save side-effect. The unexplained `session` parameter is the only notable gap for a 3-parameter tool.

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%, so the description must compensate. It explains `limit` ('most recent `limit`') and `save` (writes the full journal as a replayable script, with the exact path), but leaves `session` (default 'main') entirely unexplained, so one of three parameters remains 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 resource and content: 'the raw command lines this session sent to FEMM', clarified as 'exactly what the engine executed'. It also distinguishes itself from femm_export_pyfemm_script by naming that sibling for the standalone-file case.

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?

Only forward guidance is 'Use femm_export_pyfemm_script for a standalone file', which routes one alternative case. It never states when to reach for the journal itself (debugging, auditing, replay) versus siblings like femm_status or femm_file_summary.

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

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

With no annotations, the description carries the full burden, and it does disclose what each result code computes (flux, MMF, force, torque, charge) and how the contour is discretized. However, it omits permissions, prerequisites (e.g., a solved model), and return structure, leaving the behavioral picture incomplete.

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 core definition is front-loaded, but the bulk is a dense multi-domain code table with trailing ellipses and the cryptic 'Defaults: the first three/four' that add parsing difficulty. Information density is high, though structure could be cleaner.

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?

There are no annotations and no output schema, and 3 parameters at 0% schema coverage. The codes and contour are explained adequately for invocation, but the undocumented session parameter and unclear return format leave gaps an agent would need to resolve experimentally.

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%, so the description must compensate, and it documents the 'codes' parameter exhaustively per physics domain and explains the contour format and curve-following advice. The 'session' parameter is not mentioned at all, but the two substantive parameters are well 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?

The description states a concrete verb+resource: computing line integrals along a contour of straight pieces, with explicit coordinate format [[x,y],...]. It implicitly contrasts with the area-based femm_block_integral, but never names it, so the sibling distinction is left to inference.

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?

There is no statement of when to choose this tool over alternatives such as femm_block_integral or femm_point_values. The description is a physics-code reference dump rather than usage guidance, so the agent must infer the appropriate context.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the failure condition and that no re-solve occurs, but says nothing about whether loading is idempotent, what state it changes, or whether it requires an active session.

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?

Two tight sentences with the core action and the key failure mode front-loaded; no redundant or filler content.

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 post-processor load tool with no output schema, the description covers the action and its main failure mode. The gap is the undocumented session parameter, which is the only input and is left entirely unexplained.

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%, and the single 'session' parameter (default 'main') is undocumented in both schema and description. For a 1-param tool at 0% coverage, the description should explain what the session selector means but does not.

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 gives a specific verb and resource ('Load the existing solution ... into the post-processor') and clarifies it does not re-solve, which implicitly separates it from femm_solve. It is clear what the tool does, though it does not explicitly name the sibling it complements.

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 states a precondition ('Fails if the model was never solved') and distinguishes from re-solving, which implies the use case of post-processing an already-solved model. However, it never explicitly says when to choose this over alternatives such as femm_solve or the various result tools (point_values, block_integral).

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

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

With no annotations, the description carries the full burden and mostly delivers: it discloses that a text file is written (a side effect), that it works headless, and that the return includes the file path, column header, and min/max/mean of sampled values. It does not say whether a solved problem or open session is required, but the core behavior and return payload are well covered.

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 action is front-loaded in the first sentence, followed by dense but necessary plot_type enumerations that compensate for zero schema description coverage. It is somewhat heavy but every block earns its place; nothing is padding.

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?

With no annotations and no output schema, the description does cover the return payload (path, header, min/max/mean) so the agent knows what comes back, and it explains the plot_type/contour semantics well. The gaps are the undocumented npts and session parameters and any prerequisite about needing a solved problem.

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 so for the hardest parameter by fully enumerating plot_type codes per physics mode and describing the contour format. However, npts, session, and (partially) path are left undocumented, so coverage of the 5 params is incomplete.

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 gives a specific verb+resource: 'Sample a quantity along a contour ... to a text file.' It also states the mechanism (xo_makeplot) and that it works headless, which is concrete. However, it never names or contrasts with the adjacent sibling femm_plot_field, so an agent must still infer which plotting tool is appropriate.

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 — sample a quantity along a contour and export to text — and 'works headless' is a useful operational note. But there is no explicit when/when-not guidance and no routing to alternatives such as femm_plot_field or femm_line_integral, leaving the choice to inference.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the caching behavior ('extracted to text once and cached') and the two distinct return shapes (section text vs. snippets with section names), which is genuinely useful. However, it says nothing about failure modes (missing/manual not installed), result count, or how caching interacts with the undocumented refresh flag.

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?

Two sentences, front-loaded with the resource, and the examples are dense rather than padded. The query sentence runs long, but every clause (formats and their return semantics) earns its place.

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?

No output schema and no annotations, so the description is the only source of truth. It covers the primary query path well but leaves the refresh and max_chars knobs, plus error behavior, unaddressed — a meaningful gap for a 3-parameter tool.

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. It thoroughly explains the `query` parameter's accepted forms and their differing output, but `refresh` and `max_chars` are never mentioned, leaving two of three parameters entirely 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: 'Read the installed FEMM 5 manual (manual.pdf...)'. It also clarifies the query-response contract (headings return section text, keywords return snippets). It does not name which sibling it contrasts with (e.g. femm_api_search, femm_examples_list), so an agent must infer the boundary itself.

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 accepted query forms are stated, which implies how to use the tool, but there is no explicit when-to-use or when-not-to-use guidance and no mention of the alternative documentation tools (femm_api_search, femm_api_get, femm_examples_list). Usage is implied rather than routed.

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

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.

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

With no annotations, the description carries the full burden and does well: it discloses that clear_first removes the existing curve (a destructive behavior), the strict ordering constraints on points (starting at [0,0], strictly increasing), and the prerequisite state. It omits session behavior and any error/failure semantics.

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 action, then branches into the two problem-type formats and the clear_first/prerequisite notes. The parenthetical API function names (mi_addbhpoint, hi_addtkpoint) add specificity without much bloat; the text is dense but every clause earns its place.

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?

No output schema and no annotations, so the description must stand alone, and it largely does: both physics variants, point formats, clear_first destruction, and the material-existence prerequisite are covered. Only session semantics and return behavior are unaddressed, minor gaps for this operation.

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%, so the description must compensate, and it does for 3 of 4 params: `name` is the target material, `points` gets full format detail including units and ordering rules per problem type, and `clear_first` is explained. Only `session` (default 'main') is left unexplained.

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: 'Give material `name` a nonlinear curve', covering both magnetics (B-H) and heat-flow (T-k) variants. This clearly distinguishes it from generic material tools, though it doesn't explicitly contrast with the sibling femm_material_modify, which an agent might confuse it with.

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?

Gives a concrete prerequisite: 'The material must already exist in the model (femm_material_add or femm_material_load)', naming the setup tools. It doesn't explicitly state when to prefer this over femm_material_modify or femm_material_add, so no exclusions are provided.

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

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

No annotations are present, so the description carries the full burden, and it does well: it discloses the full contents of the returned record, the effect of include_curve, and notably the miss behavior (returns suggestions and a 4.2->5 rename). It omits any statement about safety/permissions, but as a read operation that gap is minor.

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?

Three dense, front-loaded sentences that lead with what is returned and then cover the optional curve and miss handling. The parenthetical field lists are long but each element is informative, so little is wasted.

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?

With no output schema and no annotations, the description usefully documents the return contents and the miss case, which is exactly what is missing elsewhere. The uncovered physics parameter and absence of any read-only reassurance are the remaining gaps for a 3-param retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.