kernelCAD

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

Annotations already disclose that the tool is not read-only, is idempotent, and is non-destructive. The description adds useful behavioral detail—durable insertion into source, return of modified source plus re-evaluation diagnostics—but the final claim 'Side-effect-free' sits in tension with 'Durably insert' and readOnlyHint=false, which muddies rather than clarifies the mutation 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?

Four short sentences, front-loaded with the trigger condition and followed by the concrete insertion pattern, prerequisite, and return behavior. The 'Side-effect-free' sentence is questionable enough that it doesn't fully earn its place, keeping this from a 5.

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 tool with annotations, an output schema, and high schema coverage, this covers the essential call recipe: prerequisite binding, insertion location, and return shape. Missing are edge cases such as duplicate connector names or failure diagnostics, but the definition is sufficient for 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 coverage is 86%, so parameter documentation is already largely handled by the schema. The description only adds the relationship between part_binding and add_part, plus shows the optional axis/normal slots in the API signature; it does not explain connector type semantics or the topology-derived origin forms that the schema describes.

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 a mate connector to a part') and even shows the exact API call to insert, so an agent knows precisely what code transformation results. It is distinguishable from siblings like add_part and add_mate because it names add_part only as a prerequisite.

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 states when to use it ('when you need to add a mate connector'), the required prerequisite ('Use the part binding returned by add_part'), and where the insertion must go ('before the final top-level return'). It does not name any alternative or exclusion case (e.g., add_mate vs. connector), so it stops short of a 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?

The description says "Side-effect-free," but the annotations declare readOnlyHint=false, meaning the tool may modify its environment. That is a direct conflict in mutation semantics; the rest of the behavioral note (validated constraint, updated list returned) is useful but does not resolve the contradiction.

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, front-loaded sentences with little waste. The second sentence largely restates the first, which is mild redundancy rather than a major flaw.

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?

Output schema exists and the input schema is richly documented, so return values and parameter structure need not be explained. The description covers purpose and basic behavior, but the side-effect claim conflicts with annotations, leaving the agent uncertain about mutation 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 100%, and the schema fully documents both parameters, including nested constraint fields and enums. The description merely names the parameters and adds that the constraint is "validated," without adding syntax or format detail beyond 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 and resource: "Append one validated sketch constraint to a constraint list." The phrase "sketch constraint" distinguishes it from sibling add_* tools that handle connectors, mates, curves, and features.

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?

Begins with explicit guidance: "Use this when you need to add a sketch constraint to a list." It gives clear context for use but does not name exclusions or alternative 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?

Goes well beyond the annotations by disclosing that it inserts a declaration at a specific point in existing source, returns the modified code plus diagnostics from re-evaluation, and that each kind fails closed on missing params. Minor caveat: 'Side-effect-free' sits in mild tension with readOnlyHint=false, though it plausibly means no persistent model mutation beyond the returned code. Idempotent/non-destructive hints are consistent with the text.

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 use case and insertion behavior, then a clean per-kind bullet breakdown. Some sentences restate schema-documented defaults (degree, weights, knots, closed), which is mild duplication 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?

For a two-path, 10-parameter authoring tool operating on source code, the description covers both construction kinds, required inputs, the binding/return type, failure behavior, and downstream consumers. An output schema exists, so the brief mention of returns is a bonus rather than a 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?

With 100% schema coverage the baseline is 3, so credit goes to genuinely additive guidance: tangent magnitude should approximate chord length, curvature defaults to [0,0,0] giving G1-only, controlPoints are mm Vec3 triples with a minimum of 2, and knots default to clamped-uniform. Only 'code' and 'binding_name' are left to the schema alone.

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 ('add a freeform/organic 3D curve authored as a Curve3D into the .kcad.ts') with concrete use cases (feature line, brow, spine rail, G2 blend). It also establishes insertion location ('immediately before the last top-level return') and the return type (Curve3D, peer to Shape/Surface), which separates it from add_path_segment, add_surface, and project_curve.

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 states the triggering need ('when you need a freeform/organic 3D curve') and routes downstream consumption to add_variable_sweep and add_surface boundary. It does not, however, say when to prefer siblings such as add_path_segment or project_curve instead, so the negative cases are left 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?

Adds real context beyond annotations: it declares the tool is side-effect-free and returns modified code as text plus diagnostics from re-evaluation, which explains what the caller actually gets back. There is mild tension between 'side-effect-free' and readOnlyHint=false, but the surrounding text ('returns the modified code as text') resolves it as a non-writing transform, not a contradiction.

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 trigger condition is front-loaded and every sentence carries usable information—insertion location, return content, safety, and the faceLabels pointer. The faceLabels sentence is dense and slightly tacked-on, but it earns its space.

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?

A mutation tool with an output schema, so return values need not be spelled out, yet the description still summarizes them. The main gap is failure behavior: it never says what happens when the script has no top-level return statement or an insertion would be invalid.

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?

With 100% schema coverage the baseline is 3, but the description adds meaning: feature_code must be a single statement, and inserted code may carry opts.faceLabels for the enumerated primitives, with lookup_api named as the source for the full value schema. That is genuine semantics the schema text does not supply.

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 and resource (insert a new feature line) and pins the exact insertion point: before the last top-level return statement in a kernelCAD script. That level of specificity distinguishes it from sibling mutation tools like add_part, add_curve, or remove_feature 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?

Opens with an explicit trigger ('Use this when you need to insert a new feature line into a script') and routes the agent to lookup_api for the faceLabels value schema. It does not state when to prefer a sibling instead (e.g., add_pattern_feature, add_constraint, or rewriting via evaluate_script), 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?

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the mutation profile is covered. The description adds genuinely new context: every call durably edits source, requires code and assembly_binding, and each relation fails closed on its own missing params — behavior an agent cannot infer from the annotations.

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 usage sentence followed by a tight bulleted breakdown and one closing constraint sentence. A few required-field names are repeated verbatim from the schema, but the structure is efficient and scannable for a 22-param 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 highly branched tool with 22 params and an if/then schema, the description conveys the discriminating information — which relation to pick, what each minimally needs, that code and assembly_binding are always required, and that edits are durable. Return values are covered by the output schema, so nothing essential 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 100%, so the baseline is 3. The description still adds value by compactly restating the minimal required payload per relation and noting that 'relation' defaults to 'mate' and that all other params are forwarded verbatim, which tells the agent the wrapper is not validating relation-specific fields.

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 — authoring a mate-graph relationship into the source — and decomposes it into three named relation variants with their payloads. It does not explicitly differentiate itself from siblings such as solve_mates or add_constraint, so an agent must infer that this creates relationships rather than solving 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?

"Use this when you need to author a mate-graph relationship into the source" gives an implied trigger, and the three bullets help pick a relation. There is no explicit when-not guidance or pointer to the natural follow-up (solve_mates) or to alternatives for constraint/workflow authoring.

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?

Adds substantial context beyond the annotations: where the code is inserted, that the operation is side-effect-free, that the caller must persist the returned source, and that diagnostics come from re-evaluating. One gap remains: annotations claim idempotentHint=true, but the description never explains how a repeated insert avoids duplicating the const binding, leaving that trait unverified by the text.

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 triggering condition, then the precise edit, then side-effect/return behavior — a sensible order. The first sentence is slightly redundant with the tool name, but the remaining content is dense and earns its space.

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 moderate-complexity source-transformation tool, everything needed to call it correctly is present: insertion location, immutability contract, persistence responsibility, and what comes back. With an output schema covering return shape, the description need not detail diagnostics structure.

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 100%, so baseline is 3, and the description earns an extra point by mapping parameters into the emitted template (`partName`, `shapeExpression`, `opts?`=the `at` placement) and clarifying that the shape expression is inserted verbatim. It still doesn't explain the defaulting behavior of binding_name, but the schema already documents that.

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 ('add a part to an assembly') and then pins the exact resource-level effect: inserting a `const <binding> = <assembly>.part(...)` line before the final top-level return. An agent can tell this apart from add_feature/add_mate/add_connector by the code-transformation framing, even without opening the 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 this when you need to add a part to an assembly' gives a clear triggering condition, and the insertion-point detail further constrains legitimate use. It stops short of naming alternatives or exclusions (e.g. vs add_feature or add_mate), so it is clear context but not full routing 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?

The annotations declare `readOnlyHint: false`, but the description explicitly says the tool is 'Side-effect-free' and only 'Returns the modified code + diagnostics.' That is a direct contradiction of the read-only annotation. Although the description also usefully discloses injection location, fail-closed behavior, and per-kind requirements, the contradiction dominates this dimension.

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 definition is dense but appropriately sized for a 14-parameter tool with three conditional variants. It front-loads the main use case and organizes kind-specific details in a bullet list, though some material overlaps with the schema.

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 the tool's complexity, conditional schema, annotations, and existing output schema, the description covers what an agent needs: when to use it, where the segment is injected, how each kind works, return behavior, side-effect claim, and fail-closed handling. No essential call-time context 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 100%, so the schema already carries the baseline parameter documentation. The description adds useful conceptual semantics beyond the schema, such as spline interpolation through every waypoint, NURBS as an explicit B-spline net, and Hermite G1 vs G2 tangent/curvature behavior.

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 action and target: appending a curved segment to an existing PathBuilder chain via `chain_anchor`, with three segment kinds. It is clear enough to distinguish from unrelated tools, but does not explicitly differentiate itself from sibling curve/connector tools such as `add_curve` or `add_connector`.

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 explicit usage context, including use cases like eyewear brows, ergonomic grips, sneaker midsoles, and body silhouettes, plus the structural condition of appending before `.close()`. It does not state when not to use it or name sibling alternatives, which keeps it below a 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?

Goes well past the annotations: declares the re-evaluation diagnostics returned, the single-editable-unit semantics, the `<sourceId>_pattern_<i>` face-ref naming convention, and — most valuably — that pattern is a cumulative boolean union, so subtractive features only pattern cleanly across disjoint bodies. 'Side-effect-free' is consistent with a tool that rewrites caller-supplied code rather than project 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-loaded with the when-to-use clause and then packed with genuinely load-bearing detail; no filler sentences. The geometric caveat is long and dense but earns its space because it changes whether the call will produce correct geometry.

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 nested-object tool with an output schema, the description covers the parts structured fields cannot: the placement constraint, the discriminator pairing, the returned diagnostics, and the geometric limitation on subtractive patterning. An agent has everything needed 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 86% and the if/then discriminators are machine-readable, but the description adds the human-level rule "Pass structured args (kind + the matching spec object)" that tells the agent how kind selects linear/circular/grid. It does not elaborate on count/spacing ranges or the optional angleDeg default, which the schema already covers.

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 (insert a Shape.patternLinear/.patternCircular/.patternGrid call into a kernelCAD script) and scopes it precisely relative to the broader add_feature sibling. The three pattern kinds and the required insertion point (before the last top-level return) make the operation 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?

"Use this when you need to repeat a feature in a pattern" gives a clear triggering condition, and it adds the mechanical precondition of inserting before the last top-level return. It never explicitly rules out alternatives such as add_feature or flatten_pattern, so the agent must infer the boundary itself.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds real behavioral context: each kind fails closed on missing params, specific diagnostic codes are emitted (feature.surface-sew.open-shell, feature.draft.failed), and a Surface yields no Shape until chained. However, it asserts 'Weights are honored: supply rational weights to build exact circles/cylinders/spheres' while the schema for the same field says 'Ignored in slice-1' — a direct contradiction that could mislead an agent into expecting rational geometry it will not get.

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 long, but for 23 parameters and five distinct sub-APIs the content is load-bearing, and the trigger condition plus the kind list is front-loaded. Some per-kind prose duplicates the schema's own parameter descriptions (e.g. tolerance defaults, angle range), which costs a point but not more.

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 23 params, nested objects, and an output schema present, the description covers what an agent needs: what each kind emits, ordering constraints, failure modes, defaults, and the fact that the result is not a solid until chained. The remaining gap is the unresolved weights/slice-1 conflict, which leaves ambiguous whether rational input is actually consumed.

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 100%, so the baseline is 3; the description earns above that by explaining intent per kind — e.g. that 4 boundary curves are in bottom/right/top/left loop order with endpoints coinciding within 1e-6 mm, and that knots are optional and clamped-uniform when omitted. A small deduction for the same weights contradiction and for the 'trim' gloss ('keep the largest imprinted piece') drifting from the schema's 'discards the smaller half'.

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 (author a NURBS Surface) and resource, then enumerates every path ('nurbs', 'boundary', 'trim', 'sew', 'draft') with the exact API call each emits. An agent can distinguish this from add_curve or apply_surface_blend without opening the schema, because the opening sentence scopes it to freeform/swept surface authoring and surface finishing.

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 when to use the tool ('organic, freeform, or swept shape — a body shell, panel, fairing...'), how the paths compose ('trim → sew → solid pipeline'), and explicitly routes post-authoring work elsewhere ('chain .thicken(t) or .toShape() ... do that via add_feature on the binding name'). The usage guidance is explicit, not inferred.

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?

Annotations already declare the mutation/idempotency/safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds real value beyond that: it discloses the drawText→sketchOnFace→extrude→fuse|cut pipeline, that it returns modified code plus diagnostics, and that each mode fails closed on missing params.

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 front-loaded with the when-to-use trigger and then a clean per-mode breakdown. The detail is dense but each clause earns its place; slightly long for the payload, keeping it from a 5.

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 17-parameter tool the description covers the critical complexity: mode selection, mode-specific behavior, defaults, failure behavior, and pipeline. With 100% schema coverage and an output schema present, return-value details need not be repeated, and the description is complete for 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?

With 100% schema coverage the baseline is 3, but the description adds genuinely useful mode-conditional semantics — clarifying which parameters belong to 'sketch' vs 'emboss' and the meaning of depth sign. This helps an agent select correct parameters beyond the per-param schema text.

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+resource ('author text into a kernelCAD script') and immediately disambiguates the two authoring paths ('sketch' vs 'emboss') with concrete examples (Ray-Ban temple, CE mark). An agent can tell exactly what this tool produces and how it differs from other add_* tools.

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 triggering context ('Use this when you need to author text... before the last top-level return') and explains which mode to pick for which scenario (chainable sketched text vs. engraved/embossed text on an existing face). It stops short of naming specific sibling tools to avoid, which is the only gap.

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?

Beyond the annotations, it discloses the exact insertion point in `.kcad.ts` code, behavior for empty `code`, return contents including diagnostics and `sweep` measurements, `ok:false` when nothing is built, and that the result is a Shape binding. It also explicitly notes the current orientation limitation and says the operation is side-effect-free.

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 the use case and then proceeds through spine, section, example, and return behavior in a logical order. It is dense but appropriately sized for a complex eight-parameter tool, though the long first sentence and packed clauses make it slightly harder to scan.

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 the eight parameters, mutation semantics, output schema, and geometry complexity, the description covers the insertion behavior, spine and section rules, result binding semantics, failure signal, and orientation limitation. It is complete enough for an agent to invoke the tool correctly without opening additional docs.

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?

Although schema coverage is 100%, the description adds meaningful semantics beyond the schema: `spine_points` are interpolated with `spline3d`, `spine_closed` forms a loop, sections are strictly increasing in `t` with first 0 and last 1, and profiles are centered on the spine and turned to face along it. It also explains that omitting `t` spaces sections evenly and that `t=1` on a closed spine reuses the `t=0` profile.

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: insert `variableSweep(spine, sections, opts?)` to create an organic swept solid whose cross-section changes along a length. It distinguishes the operation from generic curves/surfaces by emphasizing variable-section sweeps along a spine and naming concrete use cases such as tapering bodies, horns, and ducts.

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 a clear triggering condition: use this when the desired solid is a variable-section sweep. It also explains how the result can be chained via `add_feature`, but it does not explicitly name when-not-to-use alternatives or sibling tools for constant-section 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?

Beyond the annotations, it discloses that the insertion is durable, placed before the final top-level return, and that workspace targets are checked by solvedModel validation/review pose-envelope gates. It also says the tool returns modified source plus re-evaluation diagnostics, which is substantial behavioral context for a source-mutating 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 front-loaded with the usage condition, then gives the exact insertion form, validation behavior, and return behavior. Every sentence carries operational information and there is 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?

With a full input schema, annotations covering safety and idempotency, and an output schema, the description supplies the remaining critical context: why to use it, where the code is inserted, what validates it, and what comes back. Nothing essential for correct invocation 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 already 100%, so the baseline is 3. The description adds value by showing how the parameters compose into the emitted call (`<assembly>.workspace(connectorRef, { reachable, toleranceMm? })`), clarifying the relationship between `assembly_binding`, `connector_ref`, `reachable`, and optional `toleranceMm`.

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: declaring a reachability target for a connector by inserting a workspace call. It also gives the exact target syntax, so an agent knows precisely what operation this performs and how it differs from generic constraint or feature additions.

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 says 'Use this when you need to declare a reachability target for a connector,' which gives clear triggering context. It does not name when-not conditions or alternatives, but there is no obvious sibling tool for this specific workspace-target operation.

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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds meaningful context: it authors via the public API, returns patched source plus evaluation diagnostics, and scopes itself out of pole extraction. It doesn't mention failure modes (invalid radius, unresolvable selector) or what happens if the blend cannot be evaluated, which is the remaining 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?

Four sentences, front-loaded with the when-to-use condition, and each sentence carries distinct information (purpose, mechanism/return, selector forms, out-of-scope). The API-signature sentence is slightly dense but earns its place by mapping parameters to the emitted call.

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 7 parameters, rich annotations and an output schema, the description covers purpose, mechanism, selector semantics, and scope boundaries, so an agent can invoke it correctly. Missing only error/edge-case behavior (unresolvable selector, blend failure) which would matter for a mutation tool that patches source.

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 100%, so baseline is 3; the description adds value by showing the underlying call form Shape.fillet(radius, selector, { continuity }) / Shape.chamfer(distance, selector), which clarifies how radius/distance/selector/continuity pair up. It also spells out the EdgeSelector forms (canonical refs/query strings vs { face: ... }) and that G2 applies only to fillets — though much of this repeats schema text.

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: authoring (inserting) a fillet or chamfer blend on a kernelCAD Shape via the existing public API. It also explicitly disambiguates from the neighboring NURBS-extraction capability by saying it does not extract blend-surface poles, so an agent can tell it apart from inspect_nurbs-style siblings 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?

'Use this when you need to author and evaluate a fillet or chamfer' gives a clear triggering condition, and the closing sentence gives an explicit when-not with the alternative described ('kernel surface extraction'). It stops short of naming the concrete sibling tool for extraction, so an agent must infer the handoff, which keeps it from a 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?

Goes well beyond the annotations by disclosing that it reads no files, cuts nothing, generates no wire or route geometry, that connections are intent-only fastened mates, and that output is a script plus warnings. These constraints (idempotentHint/destructiveHint already cover safety) are exactly the behavioral context an agent needs before trusting the result as a placeholder.

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?

Densely packed but front-loaded with the 'Use this when' trigger, then data shape, then connections, then return/limitations. Every clause carries information, though the single paragraph is heavy enough that a reader must parse carefully.

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?

Covers the input shape, the units (mm), coordinate conventions, connection semantics, side effects (none), and even summarizes the return despite a full output schema existing. Nothing an agent needs to call this 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?

With only 33% schema coverage, the description compensates fully: it spells out the parts object shape, that positionMm locates the bbox lower corner in assembly coordinates, what anchors are, and that connections reference 'part.anchor' including built-in anchors (origin, bbox_center, bbox_x_min..bbox_z_max). That built-in anchor vocabulary is information available nowhere else.

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 concrete verb+resource ('need an evaluable placeholder assembly script' from a parts list with bounding boxes and positions) and clearly distinguishes itself from refinement siblings by naming add_part/add_feature as the follow-up path. An agent can tell this is the batch blockout generator, not a single-part authoring 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?

'Use this when you have a list of parts with bounding boxes and positions (from a layout, spreadsheet, another tool or a sketch)' gives an explicit trigger condition and even names typical upstream sources. It also routes onward to add_part/add_feature for refinement, though it doesn't state an explicit when-not-to-use case.

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?

Beyond the sparse annotations, the description discloses critical behavior: verification runs before browser/ffmpeg cost, collisions do not fail the call and are reported via verified:false/collisions[], turntable reports verify_skipped, focus/hide are render-only, and environment prerequisites are playwright chromium plus ffmpeg. It also explains output defaults and file resolution 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?

The description is front-loaded and every section addresses a real mode or constraint, but it is a dense wall of text with several long compound sentences. Given the tool's complexity it is appropriately sized, though tighter formatting would improve scanability.

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 17-parameter tool with both animation and turntable modes, the description covers prerequisites, mode selection, verification semantics, output formats, failure behavior, and return values. With a rich output schema also present, nothing important for correct invocation appears 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?

Although schema coverage is 100%, the description adds substantial meaning beyond field descriptions: it explains why file is required, how frames_dir changes output naming, that output_path ending in .gif changes format, turntable-specific knobs, mutual exclusivity, and how focus/hide differ from verification. This is more than a baseline restatement.

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: render a script's animationView timeline to MP4/PNG or create a 360° turntable. It clearly distinguishes the two modes (file-only animation capture vs. turntable with no animationView record) and explains the FILE ONLY constraint.

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 explicit when-to-use conditions (animation timeline to video or model turntable for sharing) and key exclusions (no inline { code } mode, frames_dir vs output_path, focus vs hide). It does not explicitly route the agent away from neighboring tools like render_preview or export, though it references the render_preview 'publish' preset.

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?

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true), so the lower bar applies. The description does add real behavioral context the annotations cannot: it continues past functional attempts with unresolved warnings, stops on ok or convergence.escalate, and explicitly does NOT autonomously rewrite full CAD models. It never states failure/error behavior or what happens when all attempts fail, which keeps it from a 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?

The very first clause is front-loaded with the trigger conditions, but the body is a dense run-on that packs the loop contract, consensus semantics, revisionAssist, and Studio record writing into three long sentences with heavy jargon (nextActionPrompt, revisionAssist.suggestedPatches, cookbook steers, stacked-primitive toys). Much of the parenthetical detail duplicates schema text, so several clauses do not earn extra space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and annotations plus a 95%-described schema carry the parameter details. For a 19-parameter orchestration tool the description still conveys the loop's stop conditions, consensus mode, and repair-prompt contract. Only failure-path behavior and how attempts are ordered/aborted is left 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 coverage is 95%, so the schema documents nearly every one of the 19 parameters and the baseline is 3. The description adds one genuinely extra piece of semantic intent for consensus:true (geometric medoid selection when picking among N candidates for the same goal) and the autoRevise hint-vs-patch distinction. That is marginal added value over an already-complete schema, not enough to lift it.

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 ('Runs a CAD design loop over attempt scripts') with the loop's core contract stated: review each attempt, continue past functional attempts with unresolved warnings, return repair prompts. It explicitly distinguishes itself from one-shot alternatives (evaluate_script+open_in_studio), so an agent can route correctly 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?

Opens with an explicit trigger list (complex/production/enclosure/gearbox/robot-arm/multi-body) and declares 'PREFERRED over one-shot evaluate_script+open_in_studio for Adam-level parts.' It also names a distinct usage mode (pass N candidates with consensus:true when there is no judge), covering when-to-use and the main alternative.

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?

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial context beyond them: the exact checks run, their thresholds and defaults, the pass/fail/warn outcome space, diagnostics, and the precedence rule that dfmSpec settings act as defaults while call options win.

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 use case and return shape, then organized by process (FDM block, CNC block, return shape, precedence). It is dense and list-heavy, but every clause carries operational information and nothing is redundant with the title.

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 11-parameter, zero-required, multi-check tool this covers everything an agent needs: input alternatives, defaults, per-check trigger conditions, result shape and the sibling to use for a different class of checks. The output schema exists, but the description's restatement of verdict/checks semantics is additive rather than filler.

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 100%, so the baseline is 3; the description still earns credit by explaining derived semantics the schema cannot, e.g. that min-wall triggers under 2 × nozzle_mm and min-hole under 5 × nozzle, and that listing several approach_axes corresponds to several CNC setups. Some defaults (printer, max_bridge_mm, tool_diameter_mm) are simply restated from 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 and resource ('returns a pass/fail checklist' for a 'manufacturability (DFM) report') and bounds the scope to pre-printing/machining review. It also distinguishes itself from the nearest sibling by explicitly routing script-declared gates to verify({ check: 'dfm' }).

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?

Opens with an explicit when-to-use trigger ('before printing or machining a part') and names the alternative with its selecting condition ('For the script-declared gates ... use verify'). It also clarifies that no dfmSpec(...) declaration is needed, removing the most likely invocation mistake.

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?

Annotations already declare read-only/non-destructive, but the description adds material context beyond them: the fail-open behavior when the render pipeline is unavailable, the name-then-positional body pairing rule and the `unmatched` error it raises, and the verdict precedence ordering. It also restates the no-session-mutation guarantee, which is the operational fact an agent needs before calling.

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 selection criterion and the sibling contrast before the mechanics, which is the right order. It is dense and the long enumeration of returned deltas/verdict values partly duplicates the output schema, costing it a point on economy, but no sentence is 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 7-parameter tool with an output schema and nested param object, the description covers inputs, pairing/error semantics, and behavioral caveats. Because an output schema exists it need not describe return fields, yet the verdict-precedence line still gives an agent a decision rule it would otherwise have to infer.

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 already 100%, so the baseline is 3; the description still adds interpretive value by framing the parameters as a base/revised pairing and explaining that `params` is a re-lowering of the baseline with declared param() values (the one-script form of a sweep). It does not add much on `render`/`out_dir` beyond what the schema says.

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 — geometric/material diff between two model versions — and immediately contrasts it with the sibling diff_scripts ("the deeper sibling of diff_scripts"), including why a volume delta alone is ambiguous. An agent can distinguish it from every other tool in the sibling list 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?

Opens with the selecting condition ("Use this when you need to know WHAT MATERIAL changed... not just how much") and names the simpler alternative. It then enumerates the legal baseline/revised combinations, including the param-sweep form, so the agent knows which invocation mode applies to its situation.

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?

Beyond the read-only, idempotent annotations, it discloses the detailed return shape: per-part added/removed/renamed/changed entries, interference-volume deltas, mate-graph changes, parameter changes, error handling, and multi-body behavior. It also clarifies that it never touches the active session and how to pass code on hosted servers.

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 front-loads the core use case, then packs return details, edge cases, and hosted-server guidance into a dense but purposeful block. Every sentence adds operational information for an agent deciding whether and how to call the 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?

Even though an output schema exists, the description supplies enough context about the diff result, error handling, multi-body behavior, and hosted/local input modes for an agent to invoke it correctly. The annotations already cover safety, and the description fills in the remaining behavioral and input-mode 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 already documents all four parameters at 100% coverage, so the baseline is 3. The description adds meaningful value by naming accepted aliases such as `base_code`, `old_code`, `before`, `revised_code`, `new_code`, and `after`, which are not present 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?

The description uses a specific verb and resource: it computes a structured geometric delta between two versions of a kernelCAD script, with explicit baseline and revision inputs. It clearly distinguishes script diffing from generic inspection by referencing per-part stats and by naming script concepts such as `(root)` pseudo-parts and `body[0]` multi-body handling.

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 says to use this after editing a script to verify physical changes before re-rendering, and it explains the hosted-server inline-code pattern. It does not explicitly compare itself to the similar `diff_geometry` sibling or state when not to use it, which keeps it from a 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?

Annotations only declare the generic mutation/open-world profile, and the description adds substantial context beyond them: it is deterministic with no vision model, dimension text overrides measured lengths, disagreements are preserved as open facts, the raster-only failure code is named, and hosting constraints (https URL, data: URI max 25 MB, asset:<id>) are given. The only gap is that it doesn't say what `script` looks like structurally or how expensive the verify re-projection pass is, which matters for a non-idempotent, non-read-only 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 routing condition is front-loaded in the first sentence and every subsequent sentence adds a distinct fact (line classification, dimension precedence, output artifacts, verify verdicts, failure mode, hosting). It is, however, a single very dense paragraph with no breaks, and a few clauses (e.g. the full list of role-named params) could be trimmed without losing 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 complex tool with 7 parameters, an output schema, and a verification pipeline, the description covers input contract, internal behavior, failure mode, downstream resolution workflow, and the meaning of the returned ledger states. Nothing an agent needs to call this correctly or to interpret the result 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 already 100%, so this is baseline-plus: the description explains the side effect of `out` (ledger written as <stem>.ledger.json beside it) and the default semantics of `verify`, and reiterates the hosted-vs-local input contract for `path`/`pdfBase64`/asset. It doesn't clarify `page` or when to override `projection`, but the value-add over the schema is real.

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 (convert a 2D engineering drawing PDF into a parametric .kcad.ts script) and immediately distinguishes it from the sibling trace_from_image by input type ('drawing PDF ... not a photo'). The mechanism is spelled out (vector linework, dimension-to-line association, extrude/revolve), so an agent knows exactly what class of operation this is.

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?

Opens with an explicit when-to-use clause keyed to the input being an orthographic PDF, names the alternative for the excluded case ('A scanned (raster-only) page ... use trace_from_image'), and closes the loop on follow-up tools (resolve_assumptions then set_param for open facts). No inference is required to route correctly.

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?

Annotations already flag a non-read-only, open-world operation, and the description adds real substance: it reads material and thickness from the CAD, hits live supplier offers, reports missing prices/blockers, and only writes a draft with no charge or checkout. Remaining gaps are minor — no mention of whether the draft persists, how long a live-quote lookup takes, or failure modes.

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 purpose is front-loaded in the first sentence, followed by what the server does, then the no-side-effects disclaimer, then the auth caveat. Every sentence adds new information; none restates the name or title.

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 tool with full schema coverage and an output schema, the description covers what an agent needs: scope (whole assembly), mechanism (CAD reads + live supplier lookup), side-effect boundary, and auth requirements. Return-value detail is correctly left to the output 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema doesn't: materials and sheet thickness come from CAD rather than from `params`, and `projectSlug` use requires sign-in while source/public projects can be estimated as a guest. That clarifies parameter choice beyond the field-level text.

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 ("Prepare an indicative estimate and durable manufacturing checklist for a whole CAD assembly") and scopes it with mixed materials/processes. It also implicitly separates this tool from ordering siblings by stating it does not send an order, charge, or start checkout.

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 clearly establishes when this tool fits (a whole assembly, mixed materials, wanting a draft estimate plus blockers) and when it doesn't (ordering/checkout). What it lacks is naming the actual alternatives — e.g. order_part, request_assembly_quote, price_part, dfm_review — so an agent must infer sibling routing from the tool list.

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?

Annotations only declare not-read-only, open-world, non-idempotent, and non-destructive; the description goes much further by disclosing that full evaluations update the active session and viewer state and keep step evidence, that dryRun leaves the session untouched, that hosted builds do not start a loopback viewer, snapshot PW_CDP_URL requirements, and the failure gates that set ok:false. No annotation conflict is present.

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 dense wall of text: the core run statement is not front-loaded, numerous parenthetical asides interrupt the main flow, and dryRun's session behavior is stated twice. Many details are useful but need restructuring into a short purpose sentence followed by grouped usage and behavior notes.

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 evaluator with an output schema, it covers the critical behavioral context an agent needs: session effects, dryRun tradeoffs, mechanism and union failure modes, hosted asset constraints, and viewer/dimension output. The remaining parameters are fully documented in the schema, and return values are covered by the output 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 100%, so the baseline is 3, but the description adds meaningful semantics for key parameters: code vs file selection, dryRun's precise scope and limits, and skipMechanismCheck's default gate and opt-out behavior. It leaves baseline, kernel, intent, and requirements to the schema, so it does not fully compensate beyond the already rich 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?

It names a specific verb and resource ('Run a kernelCAD .kcad.ts script') and enumerates the primary outputs (pass/fail, feature count, diagnostics, sceneSummary), so the core operation is unmistakable. However, it does not directly contrast itself with sibling validation/inspection tools such as verify or review_cad, and the core run statement is buried after viewer-mode details.

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 explicit when-to-use guidance ('Use this when you need to run a script and check it compiles'), explains when to choose dryRun ('fast validation while iterating') and the need to finish with a full evaluation before session-dependent tools, and states when to opt out of mechanism checks. Hosted-vs-file constraints and alternatives to full builds are also spelled out.

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?

Annotations already cover the safety profile (readOnlyHint, idempotent, non-destructive), and the description adds genuinely new context: units in mm and the sign convention (negative = inside, 0 = on surface, positive = outside). It restates the return shape '{ distance, inside, aabb, kind }', which the output schema already provides, so it stops just short of full marks.

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 trigger and the core action, then units and sign semantics, then the materialize alternative, then the binding prerequisite. Dense and useful, though the explicit return-shape listing mildly duplicates the output schema.

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?

Complete for a read-only sampling tool: the agent knows when to call it, what to pass (including the file-vs-code choice), the prerequisite binding, the units/sign meaning, and what it is a cheap check for before an expensive 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 100%, so baseline is 3, but the description adds meaning beyond the schema: it explains that fieldName must correspond to a sdf.bind binding and that the caller passes either { file } or { code } plus fieldName and point. That is real invocation guidance the schema alone does not tie together.

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 (sample the signed distance) and resource (an sdf.* field) at a 3D point, and even names the return payload. An agent can distinguish this from the many add_*/inspect siblings without opening the 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?

Explicitly conditions use ('use this when you need to sample... at a point') and names the alternative step it precedes: verifying SDF composition before the expensive sdf.materialize. It also states the prerequisite that the script must bind the field via sdf.bind('<name>', field).

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?

Adds real behavior beyond annotations: bounded vendor timeouts, an explicit status with stage resolve|evaluate|open_in_studio, the hosted-MCP caveat for openInStudio, and the strong warning that dryRun:true is capture-only and not evidence of a solid or safe result. Annotations already declare readOnlyHint=false/openWorldHint=true, so this is supplementary rather than load-bearing, but it is substantive.

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 trigger ("Use this when..."), which is good, but it is one dense chained paragraph with semicolons, inline arrows, and repetition — the dryRun-is-not-evidence warning appears twice in the description and again in the schema. It would read better as short separated lines.

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 orchestrator with an output schema, it covers the decision path, the resolve/evaluate/publish stages, the hosted-MCP constraint, and the failure/verification discipline. Return-value detail is correctly left to the output schema; only the interaction between `project`, `new_project`, and `continue_design` is left to the schema alone.

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 100%, so the schema already documents every parameter's meaning, including the dryRun caveat and openInStudio precondition. The description mainly restates those semantics plus the id-vs-query fallback ordering, which is a modest increment over the structured data.

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 compound action: resolve a cookbook snippet by `id` or BM25 `query`, evaluate its body via evaluate_script with bounded vendor timeouts, and optionally publish via open_in_studio. It explicitly positions itself against lookup_cookbook and evaluate_script, so an agent can distinguish the composite tool from the primitives without reading 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 routing rule: after lookup_cookbook for industry demos, prefer execute_cookbook when evaluate+Studio are needed together, and clarifies that an empty lookup is not a stop (freehand-author instead). It also names the precondition for openInStudio (green full evaluate) and the requirement to finish with dryRun:false before claiming success.

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?

Annotations already establish that this is a safe, read-only, idempotent planning operation. The description usefully adds behavioral details: assembly_order fallback to input order, reporting of unknown order references, axis versus radial movement semantics, and the exact output artifacts generated.

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 dense but front-loaded paragraph with no empty filler. It could be slightly more scannable, but every clause contributes useful planning or invocation context.

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 the output schema and strong annotations, the description is complete enough for an agent to call the tool correctly. It explains inputs, optional fallback behavior, mode semantics, and the major returned artifacts.

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 high at 83%, so most parameter meaning is already documented. The description still adds value by clarifying the expected part tuple format, assembly_order fallback/reporting behavior, and how mode changes the explosion strategy.

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 a specific verb and resource: producing an ordered exploded-view plan for an assembly. It is distinct from most sibling tools, but it does not explicitly contrast itself with related tools such as capture_animation or blockout_assembly.

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 a clear triggering condition: use when you need an ordered exploded-view plan for an assembly. It does not name alternatives or state when not to use it, so it falls short of full routing 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?

The description adds substantial behavioral context beyond the annotations: files are written on the hosted server, downloads use expiring HTTPS URLs, heavy formats may defer with a job_id to poll, small text files may be inline, and verification failures still write files for inspection. These details materially affect how an agent should handle results and are consistent with the annotations.

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?

Although it is front-loaded and organized by target and format, the description is extremely long and contains duplicated passages, including a repeated svg-drawing phrase about bounding-box dimensions and inter-part occlusion. It also repeats substantial schema detail, so it is not appropriately concise despite the tool's genuine complexity.

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 the large number of formats, hosted-server behavior, deferred execution, verification defaults, download-link semantics, and target-specific failures, the description is complete enough for an agent to call and handle the tool correctly. Output behavior and failure modes are well covered alongside the structured schema and annotations.

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 already 100%, so the baseline is 3, but the description adds useful control semantics: target-specific required parameters, server-side meaning of output_path, the no_verify gate, feature_id defaulting, and the model/part behavioral split. Much of the nested options detail is duplicated from the schema, but the description still improves parameter understanding.

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 a specific action and resource: exporting geometry to a file, with two explicit targets ('model' and 'part') and a long format list. It is unambiguous what the tool does, but it does not directly distinguish itself from siblings such as fab_pack, write_bom, or get_model_mesh.

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 opens with an explicit usage trigger ('Use this when you need to export geometry to a file') and explains how to choose between the two targets. It also gives targeted operational guidance for deferred exports and for calling open_in_studio instead of blocking on STEP, though it does not compare against all adjacent sibling 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?

Goes well beyond the annotations (readOnly/openWorld/idempotent) by disclosing that per-file export gates apply, that a failing format is reported in files[] while the rest still ship, that manifest.json/README.txt are written, that quote links are plain web pages with nothing uploaded or ordered, and that multi-body files are rejected by shops. That is exactly the operational context an agent needs.

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 use case and the core output, then scope/formats/processes details. Dense but nearly every clause carries information; only the hosted-server note is repeated at the end relative to the schema.

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 an output schema present and annotations covering safety, the description supplies the remaining gaps — failure behavior, generated artifacts, quote-link contents, and the no-upload caveat. An agent has everything needed to call this 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 100%, so parameters are already documented; the description still adds real semantics, notably that 'dxf' should be added for flat/sheet parts, that formats default to step/stl/3mf/pdf-drawing/bom-csv, and that processes narrows both links and (in bom scope) which rows are packed. Minor gap: it doesn't elaborate on name/output_dir beyond 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 and resource — packages fabrication files into a directory plus zip and returns instant-quote links — and implicitly separates itself from export (single-file) and order_part/price_part. An agent can tell exactly what comes out of this call.

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?

Names the trigger ('when the user wants to get a part made'), explains the part vs bom scope choice, says formats/processes narrow results, and gives an explicit prerequisite: 'Run dfm_review first if you have not.' Alternatives are effectively 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces rather than contradicts them with 'Never meshes, solves, or writes.' It adds genuine context beyond annotations: toolchain availability reporting, the install command when absent, fallback to the in-process voxel solver, and the material table with real E/Poisson/yield values.

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 paragraph, front-loaded with the when-to-use clause, and every sentence carries information. It is somewhat run-on with stacked parentheticals (solver fallback, toolchain.default_solver, material fields), which costs a bit of scannability.

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 one-optional-parameter read tool with readOnly annotations and an output schema, this is complete: it covers purpose, prerequisite (prior run_fea output_dir), fallback behavior, and the content of the returned material table. Nothing an agent needs to invoke 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 coverage is 100% and the schema already explains omitting output_dir, so the baseline is 3. The description reinforces the link to run_fea ('pass the same output_dir') and states what the omit path returns (toolchain status + material table), which meaningfully clarifies parameter effect.

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 (returns the stored FEA summary) and immediately pins its scope: context for a structural check without a solve. It is clearly distinguishable from the sibling run_fea, which it names and contrasts 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?

Explicitly says when to use it ('when you need a structural check's context without paying for a solve') and points to run_fea as the alternative that produces the output_dir it consumes. The 'pass the same output_dir' instruction ties usage to the sibling workflow directly.

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?

Beyond the annotations, the description discloses important behavior: remote STEP download implications, a 45-second timeout with errorCode parts.lookup.timeout, and the instruction not to retry in parallel. It does not describe authentication or return structure, but the output schema already covers returns.

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 short, front-loaded with the purpose, and every sentence adds useful operational guidance: offline preference, timeout/error code, and retry constraint. 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?

With 8 parameters, nested model options, and only 38% schema coverage, the description leaves meaningful gaps around how to choose between id/query/family/category/standard. Annotations and the output schema reduce the burden, and the timeout/retry guidance helps, but the definition is only minimally complete for 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 only 38%, and several top-level parameters such as id, query, family, category, and standard have no descriptions. The description adds little parameter-level meaning beyond saying it fetches one bundled catalog part, so it does not 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 first sentence gives a specific verb and resource: "Fetch one bundled catalog part." It is clearly a retrieval tool, but it does not explicitly distinguish itself from siblings such as find_part or import_step, so it stops short of a 5.

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 explicitly prefers `await lib.standard.nema17()` and `await lib.standard.bearing608()` for common standard parts because they are offline and avoid remote STEP downloads. It also gives a concrete retry prohibition, but it does not explain when to use this tool instead of sibling part tools like find_part.

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?

The description adds meaningful behavior beyond the annotations: the catalog is bundled/offline by default, remote lookups require source:"remote", parallel lookups should not be fanned out, and remote failures surface as parts.lookup.timeout within 45s. This is useful operational context even though pagination/result behavior is left to the output schema.

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 short and front-loads the core purpose. The code-snippet examples are a bit unusual and not clearly tied to this tool's parameters, but there is little wasted text.

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?

It covers the offline/remote distinction and remote failure mode well, and an output schema exists so return values need not be explained. Still, with 9 parameters and low schema coverage, the missing parameter and sibling-selection guidance leaves the definition only adequately 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 description coverage is only 22% across 9 parameters, so the description needs to compensate. It clarifies only the source/partsBaseUrl relationship and leaves tag, limit, query, family, category, and standard effectively 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 resource: searching the bundled parts catalog, and clarifies that it is offline. It does not distinguish this from nearby siblings such as fetch_part or add_part, but the core purpose is clear.

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 constraints: avoid parallel lookups, do not pass partsBaseUrl unless source is remote, and remote lookups time out after 45s. However, it does not explain when to use this tool instead of sibling tools such as fetch_part, order_part, or price_part.

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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful beyond-annotation context: the hard precondition of at least three non-collinear finite points, the deterministic nature of the normal, and the fact that it produces parameters rather than geometry.

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 trigger condition, then states outputs, then the exclusion and the precondition — a sensible order with no filler. The only minor waste is enumerating return fields that the output schema already covers.

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 single-parameter computational tool with full schema coverage, an output schema, and rich annotations, the description covers the trigger, the input provenance, the preconditions, and the scope boundary. An agent has everything needed to call it correctly without guessing.

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 100% and the single parameter is already documented as [x, y, z] triples in model units, so the baseline is 3. The description still adds meaning the schema cannot: the points must be finite and non-collinear, and they may originate from either scan data or mesh vertices.

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 (fit an orthogonal least-squares plane) against a specific resource (XYZ point-cloud data), and explicitly distinguishes itself from a surface-creation tool: 'Computes parameters only; it does not create a surface body.' An agent can tell this apart from siblings like add_surface or mesh_summary 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?

Opens with an explicit trigger condition ('Use this when you need to fit...') and clarifies input provenance ('points already parsed by the caller from scan data or mesh vertices'), which tells the agent this is not a scanner-reading tool. It does not name an alternative for when the agent actually wants a surface body, leaving that inference 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the geometric result shape and the geometric limitation around crossing bends. It does not cover error behavior or what happens when the Shape is not sheet-metal, which keeps it below a 5.

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 tight sentences with the purpose, the return shape, the geometric constraint, and the input contract, in that order. Nothing is repeated from the schema and no sentence is 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?

An output schema exists, yet the description still usefully sketches the Region's composition; the input contract and geometric limits are covered. The remaining gap is the unexplained `code` parameter and no hint about failure conditions, which matters somewhat for a zero-required-parameter tool where input selection is ambiguous.

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 only 33% — just the `file` parameter is documented — so the description does real work by stating '{ file } or { code }' mutual exclusivity and explaining that `featureId` picks a specific Shape. However, it never explains what `code` actually is (script source? model code?), leaving one of three parameters opaque 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 and resource: 'Return the unfolded 2D flat-pattern of a bent sheet-metal Shape as a Region'. It also enumerates the Region's contents (outer polyline, holes, bend lines, sketch plane), so an agent knows exactly what operation and output to expect. No sibling tool performs this transformation, and the name/title/description align without redundancy.

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 this when you need the unfolded flat pattern of a bent sheet-metal part' gives a clear triggering condition, and the note that 'crossing bends need corner relief' pre-empts a failure mode. It stops short of naming when-not-to-use or pointing to an alternative tool, but no sibling is a plausible substitute for flattening.

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?

Annotations only declare readOnly/destructive/openWorld; the description adds substantial context beyond them — determinism of output bytes, that the image reflects the server model and NOT the user's Studio camera, auth rules by visibility, the mesh_timeout error semantics, and the never-blank guarantee. This is exactly the behavioral disclosure the structured fields cannot carry.

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 sentence and the structure moves from purpose to routing to gotchas. It is quite long, and the determinism/camera points are reiterated, but nearly every sentence defends against a distinct real failure mode rather than 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?

Even with an output schema present, it covers the operational facts an agent needs: default view behavior, auth-by-visibility, error shapes, and the push-then-render workflow. Nothing required to invoke 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 coverage is 100%, so the baseline is 3, but the description genuinely extends the schema: it details the default contact-sheet behavior including the 3x2 grid layout and row ordering, which the enum description only summarizes, and clarifies the paths_only delivery tradeoff. This adds meaning beyond the 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 first sentence states a specific verb+resource+outcome: 'Render a project's current model server-side and return it as an inline image.' It also explicitly distinguishes itself from open_in_studio and implicitly from render_preview by naming the conditions under which this tool, not those siblings, is correct.

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-to-use is given: prefer open_in_studio for the happy path, use this for a different view, a contact sheet, or when you only have a slug and are not publishing. The when-not and the alternative are both named, leaving nothing 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds beyond by specifying exact return content (positions, indices, normals) and delivery mechanism (MCP Apps bridge). No contradictions.

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 cover purpose, usage context, and auth. Front-loaded with the core action, zero wasted words.

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 the tool has a single parameter, annotations, and an output schema (not shown), the description fully covers purpose, usage context, auth requirements, and data type. No gaps identified.

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 100% with a clear description for 'slug'. Description adds context about slug's role in capability/authorization, which is valuable beyond the schema field 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?

The description uses a specific verb ('Return') and resource ('per-feature triangle mesh') and clearly differentiates from siblings like 'mesh_summary' or 'get_latest_render' by specifying raw mesh data (positions/indices/normals).

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 states the tool is 'for the in-chat 3D viewer widget' and explains auth requirements based on slug visibility. Could be improved by stating when not to use (e.g., if only summary needed, use mesh_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?

Annotations cover the safety profile (readOnlyHint, destructiveHint=false), but the description goes well beyond them: it discloses that private projects and listing mode require the owner's OAuth connection, that listing mode does not paint, and it explains the paint-phase semantics (projectSaved/meshReady reflect fetch state; viewerPainted stays false). That is unusually rich behavioral context for a read 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?

Purpose and mode selection are front-loaded, but the back half is dense jargon ('Paint phases: projectSaved/meshReady ... viewerPainted stays false') that is hard to parse and would benefit from restructuring. The sentences are information-packed rather than wasteful, but the wall-of-text delivery hurts readability.

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 a rich output schema and full annotations, the description needn't explain return values, and it covers both modes, auth requirements, alternatives, and paint behavior. The only gap is that the paint-phase explanation is cryptic rather than clarifying, but functionally an agent has everything needed 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 description coverage is 100%, and the schema already documents that `slug` comes from a listing or /p/<slug> link and that omitting it triggers listing. The description restates this plus the workflow of reusing the slug with open_in_studio, but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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 (fetches/lists) and resource (kernelCAD Studio project / signed-in user's saved projects), and explicitly names the sibling it differs from (list_my_projects, open_in_studio, get_model_mesh, get_latest_render). An agent can distinguish the two modes and route correctly 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?

Explicit when-to-use for both modes: pass `slug` to fetch, OMIT it to list, and it names the preferred alternative for listing ('prefer list_my_projects'). It also states the downstream workflow (edit then open_in_studio with the same slug) and gives a negative instruction ('do NOT call get_model_mesh or get_latest_render for interactive paint').

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?

Annotations already declare readOnlyHint/destructiveHint, so safety is covered; the description adds real value beyond them by disclosing the access model — public/unlisted use slug as capability while private projects require the owner's OAuth connection. It also emphasizes immutability of the returned revision.

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, each earning its place: the first defines the resource and scope, the second gives the workflow and the access caveat. Front-loaded and free of 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?

An output schema exists, so return values needn't be explained; the description still hints at what to do with the result ('hash or inspect'). Auth requirements and input provenance are covered, leaving little an agent needs missing before calling 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 100%, so both params are already documented with provenance and constraints. The description reinforces that the slug/version come from open_in_studio but adds no format or syntax meaning beyond the schema; baseline 3 applies.

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 ('Fetch') and resource ('the exact immutable .kcad source and parameters'), scoped to a prior open_in_studio version. This clearly separates it from get_project and get_latest_render, which return current/other artifacts.

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 context: 'Use this to read-after-write verify a release' and ties the slug/version inputs back to open_in_studio. It stops short of naming a mutually exclusive alternative for other retrieval needs, so it is clear but not fully 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: what is returned (one face/edge or null), the rebuild-pending null state, that ambiguous/deleted faces are cleared, and that a running local Studio on the same script is required. This is exactly the extra behavioral context the bar asks for.

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 use case, then return semantics, then prerequisites. Every sentence carries information, though the rebuild/pending detail is dense and could be slightly 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?

An output schema exists, yet the description still preempts surprises (null during rebuild, cleared ambiguous faces) and states the local-session prerequisite. Nothing an agent needs to call this 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 coverage is 100% and both parameters are documented there, so the baseline is 3. The description reinforces "same script" and local-only constraints but adds no syntax or format detail beyond 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 (read) and resource (human/agent selection) in a local Studio session, and the contrast with the sibling set_selection is obvious. An agent can distinguish this reader from its writer counterpart immediately.

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 this when you need to read the human/agent selection" plus "Inspect the current shape before authoring a fillet" gives clear usage context, and the hosted-session exclusion is stated. It stops short of naming set_selection as the explicit alternative for writes, so not a full 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?

Annotations already declare non-readOnly, openWorld, idempotent, and non-destructive, but the description adds substantial context: it writes files plus a starter script to output_dir (default temp dir), evaluates it, refuses non-watertight STL unless allow_open, and enforces a 50 MB limit. What is missing is any note on auth/network failure behavior for url downloads.

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, opening with the trigger condition and then the source constraint. It is long, yet nearly every clause carries operational weight; a couple of the return-shape details are arguably redundant given the output schema.

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?

Covers input constraints, side effects (file and script written), STL-specific caveats, the downstream handoff of script_path, and the return shape. For a complex import tool with nested upload objects, this is complete enough to call correctly without further guidance.

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 100%, so baseline is 3, but the description adds real value: 'give exactly one source' clarifies the mutual exclusivity of url/upload/content_base64 that the schema does not enforce, and it documents the 50 MB cap and format auto-detection vs override.

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 STEP/STL file the user designed elsewhere or a vendor model) and produces named artifacts. It clearly differs from siblings like find_part/fetch_part, which retrieve catalog parts, and mesh_to_features, which it references for editable meshes.

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 (user's own STEP/STL file) and gives the alternative condition for STL meshes (use mesh_to_features for an editable feature tree). Also names the three mutually exclusive source inputs and the size cap, leaving little 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?

Beyond the annotations, the description discloses many behavioral details: each subject's return content, partial bore flagging, exact vs heuristic hole detection, density defaults and echo behavior, multi-material's non-mutating analysis, and hosted file input restrictions including the 25 MB limit. This is rich context that helps an agent invoke the tool correctly.

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 long, but the length is justified by 24 distinct `of` modes and 17 parameters. It is front-loaded with the core purpose and then organizes each mode as a tight bullet, with hosted file guidance placed at the end. Every segment appears to earn 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 the tool's complexity, 17 parameters, enum-based dispatch, and rich output schema, the description is complete enough for an agent to choose a mode and understand the relevant constraints. The output schema can carry return-shape details, and the description still supplements it with key caveats and hosted input rules.

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 100%, so the schema already documents the 17 parameters thoroughly. The description still adds value by explaining that most subjects accept `{ file | code }`, that all parameters except `of` are subject-specific and forwarded verbatim, and by clarifying cross-parameter behavior for modes like `section`, `bom`, and `mass`.

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 a specific action and resource: 'read facts about a model', selected by the `of` enum. It enumerates each inspection subject precisely, so an agent knows what the tool does. However, it does not explicitly distinguish this tool from nearby read-oriented siblings such as `query`, `verify`, `inspect_nurbs`, `mesh_summary`, or `get_model_mesh`.

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 usage context ('Use this when you need to read facts about a model') and explains the condition for each `of` mode, including a specific note that `stack` helps find the thinnest cross-section. It does not provide when-not-to-use guidance or name sibling alternatives, so it stops short of full routing 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?

Annotations already declare readOnly/idempotent/non-destructive and openWorld; the description adds non-obvious behavioral context that the source 'may load referenced assets' (the openWorld risk) and that it 'does not update the active MCP session or write a project' (a state-effect nuance annotations can't express). These are genuine additions beyond the annotations, though permission/auth or performance characteristics are unaddressed.

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 action and return payload, then layers defaults, capability limits, and side-effect boundaries. It is dense but nearly every sentence carries distinct information; the return-field enumeration is somewhat redundant given an output schema exists.

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 an output schema present, the description need not explain return values, yet it still summarizes them, and it covers scope limits and non-mutation. A small gap remains: with zero required parameters it isn't stated what happens if neither `code` nor `file` is supplied and no prior capture exists, leaving a mildly ambiguous invocation path.

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 100%, so all three parameters are already documented, including the hosted-server caveat for `file` and the default for `feature_id`. The description reinforces the default-curve selection semantics but adds no format or constraint detail beyond the schema, so baseline 3 applies.

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 (evaluate/inspect) and resource (authored NURBS curve from kernelCAD code or file), and enumerates exactly what is returned (degree, knots/multiplicities, poles, weights, flags, parameter range). It also explicitly bounds scope away from geometry-derived B-rep edge/face NURBS and surface/blend extraction, so an agent can distinguish it from surface and inspection 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?

Gives clear selection behavior ('defaults to the last captured curve in that script; pass feature_id to choose one') and explicit exclusions ('surface extraction and blending are not supported', 'not exact geometry-derived B-rep'). It does not compare against the similarly named `inspect` or `evaluate_script` siblings, so the routing guidance is strong but not complete.

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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds real context beyond that: it is a discovery reference, it enumerates the categories returned, and it warns that NURBS freeform surfacing is easy to miss from tool names — a genuine usage caveat. Return formatting is left to the output schema.

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 when-to-use condition, then the inventory, then the discovery warning. The parenthetical method lists ('box, path, selectEdges, helix, etc') are slightly padded but each category name does convey scope. Overall dense with little waste.

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 an output schema, rich annotations, and a fully documented single parameter, the description carries only the burden of purpose and routing — and it handles both except for sibling differentiation among the lookup_* family. Nothing an agent needs in order to call 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 100% and the single 'intent' parameter is documented thoroughly in the schema itself. The description says nothing about the parameter, so it adds no meaning beyond structured fields; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource and enumerates the surface it returns (globals, Shape methods, Sketch methods, PathBuilder, EdgeQuery/FaceQuery, featureKindFaceLabels), which is far more than a restatement of the title. It does not, however, distinguish itself from the other lookup_* siblings (lookup_authoring_skill, lookup_cookbook, lookup_diagnostics), so an agent must still guess which reference lookup to 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?

Gives clear triggering conditions: 'Use this when you need to list the kernelCAD script-runtime surface' and 'Use this to discover what is callable from a .kcad.ts script', plus a strong prior: 'Call this BEFORE concluding kernelCAD lacks a capability.' It lacks explicit routing to the alternative lookup tools, which is the one missing piece.

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?

Annotations already declare readOnly/destructive-safe behavior, and the description goes well beyond them: response-size expectations (index under 16k chars, full skill ~140k chars), the caveat that 'all' should only be used if the client accepts large responses, the exact mode values the response can take, and the resource URI alternative. This is rich operational context not derivable from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.