kernelcad

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

Annotations mark readOnlyHint=true yet the description describes a write operation ('Register'), contradicting each other. No additional behavioral context beyond 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?

Two tight sentences pack purpose, prerequisite, origin flexibility, and return value with 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?

Missing details on connector type semantics (frame, axis, planar, ball) but covers prerequisites, origin, and return shape for a tool with 7 parameters and no 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?

With 86% schema coverage, the description adds value by explaining origin accepts a tuple or structured type and describing the return object, going beyond the schema's basic descriptions.

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

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

The description clearly states the tool registers a v0.6 mate-style connector on a named part of the active assembly, distinguishing it from sibling 'add_*' tools like add_mate or add_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 specifies a prerequisite (prior evaluate_script with kcad.assembly) and explains acceptable origin formats, but does not explicitly compare to alternatives or state when not to use.

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 context that the tool validates the constraint and returns an updated list, beyond the readOnlyHint and destructiveHint annotations. No 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?

Two sentences, front-loaded with purpose, no extraneous words. Every sentence adds value.

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 simple pure function: annotations cover safety, description explains input/output. Lacks detail on validation errors or return format, but acceptable given simplicity.

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 0% schema coverage, description compensates by explaining the roles of 'constraint' (new constraint) and 'constraints' (existing list). Schema only defines types; description adds semantic meaning.

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?

Clearly states it appends a validated sketch constraint to a list, using specific verb 'Append' and resource 'constraint list'. Distinguishes from siblings like add_connector (adds connector) by focusing on constraints.

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 side-effect-free nature and expected input format ({ constraints, constraint }). Implies usage when needing a pure function to add a constraint, but lacks explicit when-not or alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the side-effect-free claim and mentions diagnostics from re-evaluation, providing behavioral context beyond 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?

Two sentences with no wasted words. The description is front-loaded with the core action and concisely adds usage guidance.

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

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

No output schema exists, but the description explains the return value (modified code + diagnostics). It also provides guidance on faceLabels and references list_api, making it self-contained for an agent.

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 explaining feature_code is a single-statement line with an example, and mentions opts.faceLabels usage, enhancing understanding 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?

The description clearly states the tool inserts a new feature line before the last top-level return statement and returns modified code plus diagnostics. It distinguishes itself from sibling tools like remove_feature and list_features by specifying its action on kernelCAD scripts.

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 mentions side-effect-free behavior and guides on using `list_api` for faceLabels schema, but doesn't explicitly compare to other add_* sibling tools. It gives a usage hint but could be more explicit about when to choose this over alternatives.

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

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

The description adds value beyond annotations by noting side-effect-free behavior, capture-time diagnostics, and the return type (modified code + diagnostics). Annotations already indicate readOnlyHint and destructiveHint, and description aligns without 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 description is informative yet concise, front-loading the main action and covering key details without unnecessary repetition. Each sentence adds value.

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 complexity (nested objects, 4 parameters, no output schema), the description adequately covers the return type, usage, and parameter semantics. It mentions diagnostics and side-effect-free, making it complete for an AI.

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 description enhances the schema by explaining the meaning of tangent magnitude, curvature default, and endpoint structure. Schema coverage is 100%, but the description provides practical guidance 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 clearly states the tool inserts a hermiteG2 declaration into .kcad.ts code, specifying the resource (code) and the action (insert). It distinguishes from siblings by mentioning it bridges two curves with G2 continuity and references related functions like add_variable_sweep.

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 explains when to use the tool (to bridge curves with G2 continuity) and provides guidance on consuming the result (via add_variable_sweep, add_surface_from_boundary). It does not explicitly state when not to use, but offers sufficient context.

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

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

The description claims a write operation ('Declare a typed mate'), but annotations set readOnlyHint=true, creating a direct contradiction. No additional behavioral traits are disclosed beyond what is contradicted, making this severely misleading.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that covers purpose, connector format, mate types, and optional parameters. No unnecessary words, making it easy for an agent to parse.

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?

Despite the tool having 8 parameters and no output schema, the description omits important context such as error cases, side effects, permission requirements, or return behavior. The annotation contradiction further undermines completeness.

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 75% schema coverage, most parameters already have descriptions. The description adds some value by explaining connector ref format and that limits/pose expose 'articulated intent,' but this is incremental. A baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Declare a typed mate between two named connectors on the active assembly.' It specifies the verb (declare), resource (mate), and context (active assembly), and lists mate types, effectively distinguishing it from sibling constraint tools like add_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?

The description provides no guidance on when to use this tool versus alternatives like add_constraint or solve_mates. It does not specify prerequisites, when not to use, or typical scenarios, leaving the agent without decision-making support.

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 declare readOnlyHint=true and destructiveHint=false, aligning with the description's 'Side-effect-free.' The description adds context: insertion location, return format (modified code + diagnostics), and the nature of the operation. 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?

Four sentences, all essential: action, type, usage, parameters, return, and side-effect nature. No redundancy, front-loaded with the core operation.

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 7 parameters, no output schema, and annotations covering safety, the description covers return format, usage context, and parameter semantics adequately. Slight lack of explanation about diagnostics or error handling.

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?

Input schema has 100% coverage, so baseline is 3. The description adds value by clarifying units ('mm'), minimum points ('at least 2'), and defaults ('degree default 3'). It also explains optional parameters like knots, weights, and closed.

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

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

The description clearly states the tool inserts a nurbsCurve declaration into .kcad.ts before the last return, and specifies the resulting type is Curve3D. It distinguishes from siblings like add_nurbs_surface and add_path_nurbs_segment by mentioning downstream usage via add_variable_sweep.

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 provides clear guidance on when to use: 'consume it via add_variable_sweep (spine input) or downstream Curve3D-accepting features.' It also notes side-effect-free and returns modified code. However, it does not explicitly state when not to use or list alternatives, leaving room for improvement.

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 discloses important behavioral traits: it modifies code (contrary to readOnlyHint=true), returns modified code and diagnostics, and has a known limitation (weights ignored in slice-1). The contradiction with annotations lowers the score.

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 concise, front-loaded with the core purpose, and logically structured. Each sentence adds meaningful information without 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?

Despite high schema coverage, the description adequately explains return value structure (modified code + diagnostics) and usage patterns. It mentions limitations but does not detail error handling or diagnostics contents, which would improve completeness.

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 covers all parameters with descriptions (100% coverage). The description adds value by grouping parameters into two construction options (direct controls or skinning), which aids understanding beyond individual schema descriptions.

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

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

The description clearly states that the tool inserts a nurbsSurface(...) or surfaceFromCurves(...) call into the user's .kcad.ts file. It distinguishes between two construction methods (direct controls and skinning), which differentiates it from sibling tools like add_nurbs_curve and add_surface_from_boundary.

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 explains when to use each construction mode (controls vs. section_sketch_ids) and notes that the resulting Surface must be further processed via add_feature. However, it lacks explicit comparisons to all sibling tools, leaving some ambiguity about alternatives.

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

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

The annotation readOnlyHint=true contradicts the description which states the tool mutates the chain anchor in place and modifies the code string. This is a serious inconsistency. The description otherwise adds behavioral details (side-effect-free, injection position) but the contradiction undermines trust.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph but well-organized, starting with the main action, then detailing endpoint format, defaults, usage contexts, and behavior. Every sentence adds value, though it could be broken into bullet points for clarity.

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

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

Given no output schema, the description explains the return value (modified code + diagnostics). It covers default behavior, tolerance, and use cases for G2 blends. Missing is an explanation of diagnostics, but overall it is fairly complete for a complex tool with nested objects.

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 description adds significant meaning beyond the input schema: it explains the endpoint object format (point, tangent, curvature), the default for curvature (degrades to G1), the meaning of tangent magnitude (first derivative, not unit length), and the tolerance for a.point matching pen position. Schema coverage is 100% and description enriches all parameters.

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

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

The description clearly states the action (insert `.hermiteG2(a, b)` call), the target (PathBuilder chain on `chain_anchor`), and the positioning (end of chain, before close). It also specifies endpoint format, defaults, and use cases, distinguishing it from sibling tools like add_hermite_g2 which may not be chain-specific.

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 provides explicit guidance on when to use curvature for G2 blends, the tangent magnitude convention (not unit length), and the tolerance for a.point. It does not explicitly compare to sibling tools or state when not to use it, but the context is clear.

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

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

Annotations already declare `readOnlyHint=true` and `destructiveHint=false`. The description adds behavioral details: call injection at end before `.close()`, constraint that `controlPoints[0]` matches pen position, and that the tool is side-effect-free. 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?

The description is moderately concise with several sentences, each adding value. It is front-loaded with the core action. Could be slightly more concise (e.g., merging two sentences about controlPoints).

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 (7 params, specific constraints), the description covers the main aspects: purpose, placement, constraints, return value, and use case. Minor gaps like error handling or requirement that chain_anchor exists, but overall sufficient.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the description adds meaningful context beyond the schema, such as constraints on `controlPoints` (min length, start/end match), default degree, and positive weights requirement. This enriches 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 the tool inserts a `.nurbsSegment` call into a PathBuilder chain on a named anchor variable. It specifies the action, the resource, and distinguishes from siblings by mentioning NURBS and control net as the natural mental model.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context for when to use the tool (explicit B-spline outlines, control net modeling), but does not explicitly state when not to use it or compare to alternatives like `add_path_spline`. However, the use case is clearly implied.

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

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

Annotations already indicate read-only and non-destructive nature. Description adds critical behavior: injection location (end of chain, before .close()) and a runtime error condition (first point mismatch within tolerance). Return value (modified code + diagnostics) is stated. More detail on diagnostics format would improve, but current is sufficient.

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 concise sentences that efficiently convey purpose, injection point, error condition, usage guidance, and return value. No redundant or missing information. Front-loads the core action.

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

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

Given no output schema, the description adequately states return value (modified code + diagnostics). All required parameters are explained with examples and constraints. The tool's side-effect-free nature is confirmed. A minor gap is the lack of detail on diagnostics content, but not essential.

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 has 100% coverage. Description adds value by explaining the injection position, the tension parameter's effect (forwards to makeBSplineApproximation), and that binding_name is reserved. It clarifies the points constraint (first must match pen position) beyond 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?

Description clearly states the action (insert spline call into PathBuilder chain) and specific resource (named chain_anchor variable). It distinguishes from siblings by specifying spline interpolation with Catmull-Rom-style tension, differentiating from other curve tools like add_path_hermite_g2.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit use cases (organic 2D outlines from measured waypoints) and notes the tool is side-effect-free. Does not explicitly exclude alternatives, but the context given helps agents choose appropriately.

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 annotations (readOnlyHint, destructiveHint), the description adds significant behavioral context: side-effect-free, return of modified code and diagnostics, pattern implementation as cumulative boolean union, and geometric notes on patterning additive vs subtractive features. No contradiction with 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?

The description is concise, front-loading the main purpose in one sentence, then adding necessary behavioral notes. Every sentence adds value without 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?

Despite no output schema, the description covers the tool's action, return values (modified code and diagnostics), pattern behavior, and face reference resolution. It is sufficiently complete for an agent to select and invoke the tool 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% (high), so baseline is 3. The description only briefly says 'Pass structured args (kind + the matching spec object)', which adds minimal extra meaning beyond the detailed 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 clearly states the tool inserts a pattern call into a kernelCAD script, specifying the exact pattern types (linear, circular, grid). It distinguishes from siblings by focusing on pattern features specifically.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for adding patterns but lacks explicit guidance on when to use this tool versus alternatives like add_feature or flatten_pattern. No when-not or alternative mentions.

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?

Discloses side-effect-free nature and that it returns modified code and diagnostics, aligning with readOnlyHint=true. Adds context about default font and custom font loading beyond 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?

Four sentences, front-loaded with core action, no redundant information. Excellent structure for quick comprehension.

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 key behavioral aspects (code insertion, return values, side-effect-free, chainability), but lacks details on error handling or edge cases. Reasonably complete given tool complexity.

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 covers 100% of parameters. Description adds minor context (default Liberation Sans font, chainability hint) but does not add significant meaning beyond schema 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?

Clearly states it inserts a sketch.text(...) call into a kernelCAD script, specifying verb and resource. However, it does not explicitly differentiate from sibling tools like emboss_text, though the chainable nature is implied.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes when to use (to add text sketch) and mentions chainability with .extrude/cut, but lacks explicit alternatives or when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, confirming no side effects. The description adds value by disclosing validation behavior (regex check, corner-mismatch error), default options, and the fact results are side-effect-free, surpassing annotation coverage.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is densely informative yet well-structured, front-loading the primary action and following with algorithmic detail, parameter specifics, and validation notes. Every sentence contributes distinct value without 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?

Given 5 parameters and no output schema, the description covers the tool's purpose, algorithm (OCCT BRepOffsetAPI_MakeFilling), parameter constraints, validation, and result type (Surface). It omits explicit return structure, but overall completeness is high.

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?

Explanation adds critical meaning beyond the schema: curve_bindings order (bottom, right, top, left), continuity can be a single grade or per-edge array, and sampling default. These details reduce ambiguity, though schema coverage is complete.

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 specifies a concrete action: insert a surfaceFromBoundary declaration into .kcad.ts code. It clearly states the resource (Coons-patch surface from 4 curves) and differentiates from siblings like add_nurbs_surface by detailing the specific CAD operation and code insertion context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when you have four boundary curves to create a surface, but it lacks explicit guidance on when to choose this over alternatives like add_nurbs_surface or add_hermite_g2. No 'when not to use' or comparative context is given.

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

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

Annotations already declare readOnlyHint=true, so the description's behavioral disclosure is additive: it confirms side-effect-free, explains validation before insertion, insertion location, and constraints on sections. 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?

The description is a single paragraph that front-loads the core action. Each sentence adds value without excess. Slightly dense but appropriate for the 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 tool's complexity, the description covers the insertion point, constraints on sections, validation, and return type. No output schema exists, but the description adequately describes the return. Minor gaps: no detail on diagnostic format or error handling.

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%, baseline 3. The description adds meaning beyond schema: explains how spine_binding and profile_binding refer to existing variables, the t parameter constraint (strictly increasing, span [0,1]), and default for binding_name. This adds significant value.

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 explicitly states the action ('Insert a variableSweep declaration into the .kcad.ts'), the result type (Shape), and distinguishes it from sibling add_* tools by specifying the geometry type and insertion point.

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?

Although the description clearly explains what the tool does, it does not provide explicit guidance on when to use this tool versus alternatives (e.g., other add_* tools) or when not to use it. Usage is implied but not contrasted.

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, covering safety. The description adds context about writing a build record, which is not destructive, but does not explain behavioral traits like the loop's side effects or any persistence beyond output files.

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 concise in a single paragraph but front-loads the main action. It is comprehensive yet could be broken into structured points for easier parsing. Overall, it earns its sentences.

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

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

Given the tool's complexity (16 params, nested objects, no output schema), the description adequately explains the loop's behavior, output (repair prompts, build record), and key parameters forwarded. It is sufficiently complete for an orchestrating tool.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 94%, so baseline is 3. The description does not add meaning beyond the schema; it only mentions parameters forwarded to review_cad without elaboration. The schema itself already contains detailed descriptions.

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

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

The description explicitly states the tool's purpose: to run an agent CAD design loop over attempt scripts, review each with review_cad, continue past functional attempts with warnings, and return structured repair prompts. It clearly distinguishes itself from sibling tools by describing a composite orchestrating function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage in iterative design loops but does not explicitly state when not to use or provide alternatives. It effectively outlines the workflow and conditions (e.g., continue past functional attempts with warnings) but could be more directive.

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 declare readOnlyHint=true and destructiveHint=false, and the description confirms side-effect-free behavior. It adds depth sign explanation (positive emboss, negative engrave) and underlying replicad workflow, which goes beyond 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?

The description is concise, front-loaded with action and examples, and contains no unnecessary words. Each sentence adds value.

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?

While no output schema, the description explains the return value (modified code + diagnostics) and the overall workflow. It is fairly complete for a code-insertion tool with rich 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 100%, so baseline is 3. The description adds context for depth and face but does not detail all parameters beyond what the schema already provides. It does not compensate significantly.

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

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

The description clearly states the action (insert embossText call) and resource (kernelCAD script), with concrete examples like Ray-Ban temple. However, it does not explicitly differentiate from siblings such as add_sketch_text, which may handle 2D text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies usage for engraved brand text but provides no exclusions, when-not-to-use, or alternative tool references. The context is implied but not explicit.

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 indicate readOnly and non-destructive; description adds that it reports specific diagnostics. No mention of side effects beyond that.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no waste, front-loaded with action and outputs.

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?

Completely describes usage and outputs for a tool with no output schema and simple parameters.

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% (baseline 3), but description adds mutual exclusivity context and clarifies that file is a path and code is inline source.

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?

Clearly states it runs a .kcad.ts script and reports pass/fail, feature count, and diagnostics. This differentiates it from sibling tools like evaluate_sdf.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies passing either file or code, but does not specify when to use one over the other or mention alternatives or when-not-to-use.

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 indicate read-only, non-destructive behavior. The description adds detailed return structure, meaning of distance values (negative inside, zero on surface, positive outside), and units in mm. Exceeds annotation-only disclosure.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences: first describes core action and return type, second explains distance semantics, third provides usage guidance and parameter hint. No redundant words; front-loaded with key 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?

Covers return structure, distance interpretation, binding requirement, parameter hints, and relationship to alternative tool. No gaps given schema and annotations are present.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with descriptions for all parameters. The description adds value by explaining the mutual exclusivity of 'code' and 'file', and clarifying that 'point' is in mm. This enhances understanding 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?

The description clearly states it samples signed distance from an SDF field at a 3D point, using a specific verb and resource. It distinguishes itself from sibling tools by focusing on SDF evaluation versus other modeling operations.

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 'Use this to verify SDF composition before calling sdf.materialize', providing clear context and alternatives. Also explains the prerequisite of binding the field and hints for parameter selection.

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

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

The description reveals that the STL file is written server-side and clarifies the meaning of 'feature_count'. Annotations already provide readOnlyHint and destructiveHint, but the description adds value by explaining the side effect (file write) and return field details. No contradiction with 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?

The description is efficiently structured: first sentence states purpose, second covers parameter usage, third lists return fields, fourth clarifies a non-obvious field, and fifth adds context. No unnecessary words; every sentence earns its place.

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

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

Given the tool has 4 parameters and no output schema, the description covers purpose, parameter constraints, return values, and a nuanced field explanation. It does not mention prerequisites (e.g., script must be evaluated) or error handling, but overall it is sufficiently complete for an experienced user.

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?

Input schema has 100% coverage with descriptions. The description adds critical semantics: mutual exclusivity of 'file' and 'code', and default behavior of 'feature_id'. This information is not in the schema, so the description adds value 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?

The description clearly states the tool exports script geometry to a binary STL file, with a specific verb ('Export') and resource ('script geometry to a binary STL file'). It distinguishes itself from siblings by being the only export tool, and adds context about suitability for slicers, simulators, and viewers.

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 provides clear usage: 'Pass either { file } or { code } plus a required { output_path }' and notes the optional feature_id with default. It implies when to use (exporting geometry) but does not explicitly state when not to use or alternative tools. The context about slicers adds some 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 readOnlyHint=true and destructiveHint=false. Description adds that it returns a Region with specific geometry (polylines, holes, bend lines, sketch plane). No contradictions; no additional side-effect disclosure needed.

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, first sentence front-loads the purpose and output description, second sentence covers limitations and parameters. No 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?

Describes return type (Region) and components. Given no output schema, the description provides a reasonable overview. Lacks mention of error conditions or detailed parameter definitions, but adequate for a simple tool with few parameters.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It clarifies that file and code are alternative inputs and that featureId is optional, but does not define formats or constraints (e.g., what exactly file or code contain). Adds some meaning but incomplete.

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

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

Clearly describes returning the unfolded 2D flat-pattern of a sheet-metal shape, specifying the result components (outer polyline, holes, bend lines, sketch plane) and the limitation of at most 2 bends. Distinct from siblings like get_shape_info or list_faces.

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?

States the prerequisite (sheet-metal shape), limitation ('Slice 1: at most 2 bends'), and input options (file or code, optional featureId). Does not explicitly compare to alternatives or state when not to use, but provides sufficient context.

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

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

Annotations already declare readOnlyHint=true, and the description adds value by detailing the computed data returned (K-factor, bend allowance, etc.). No contradictions with annotations. However, it does not cover potential failure modes or permissions.

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 two sentences with no redundant words. The first sentence conveys the full purpose and output fields; the second tells how to invoke it. Every sentence is essential and front-loaded.

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

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

The description lists all the fields returned, but does not specify the output structure (e.g., array of objects) or handle edge cases. Given no output schema and low parameter coverage, the description provides adequate completeness for a read-only tool, though it could mention prerequisites.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate. It notes that 'file' and 'code' are alternative inputs (mutually exclusive), but lacks details on format, path, or script language. Baseline for zero params would be 4, but here params exist and the description provides only minimal clarification.

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

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

The description clearly states the tool lists every sheetMetalBend with detailed computed fields like K-factor, bend allowance, axis line, etc. The verb 'list' and resource 'sheetMetalBend' are specific, and no sibling tool overlaps with this exact functionality.

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 indicates that either 'file' or 'code' can be passed, but it does not specify when to use this tool over alternatives (e.g., other list tools). There is no mention of prerequisites or contexts where the tool is inappropriate.

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. Description adds the constraint that it works only on 'un-transformed primitive' and lists output properties, providing useful behavioral context beyond 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?

Two concise sentences, first stating purpose and output, second showing parameter structure. No wasted words, though could be better structured with lists or examples.

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 many siblings and sparse schema, description covers core purpose and main parameter but lacks details on optional parameters, output format details, and usage guidance. Leaves gaps for a complete understanding.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It lists the enum values for face_name and shows parameter structure, but does not explain the optional parameters (code, file, feature_id). Adds moderate value for the required parameter only.

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?

Description clearly states the tool returns boundary edges of a named canonical face on an un-transformed primitive, listing returned properties (index, centroid, length, isClosed). This distinguishes it from siblings like list_edges (all edges) and list_faces (all faces).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives among many siblings. Mentions 'un-transformed primitive' but doesn't clarify when not to use or what alternatives exist for transformed primitives or custom faces.

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 declare readOnlyHint=true and destructiveHint=false. The description adds behavioral nuance: 'Ships create/modify ops in this slice; split/delete classification is deferred', which explains side effects beyond the read-only nature. No 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 description is fairly concise, packing purpose, inputs, outputs, and side effects into a few sentences. However, it could be better structured (e.g., separate sections) for 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?

While the description mentions return shape and side effects, it does not explain the contents of 'chain' or the meaning of 'usedFallback'. No error handling or prerequisites are covered. Given no output schema, more detail on the return value would improve completeness.

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 has 100% description coverage, but the description adds value by clarifying special values like 'auto' for feature_id and giving an example format for ref ('name.slot'). It also notes the return type { chain, usedFallback }, which is not in 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 clearly states the action 'Walk the HistoryMap' and the resource 'lowered feature', and specifies the output 'chain of lineage entries'. It uniquely identifies what the tool does, distinguishing it from sibling tools like 'get_edges_of' or 'list_faces'.

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 provides input format hints but lacks any guidance on when to use this tool versus alternatives. No explicit context about when to choose get_face_lineage over other query tools, nor when not to use it.

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?

Description says 'Run + recompute', implying potential mutation, but annotations declare readOnlyHint=true. This is a contradiction. Beyond that, no detail on side effects or permissions.

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 sentence, front-loaded with action and output, no unnecessary 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?

Covers main return values despite no output schema. However, lacks error conditions and prerequisites; still adequate for a simple tool.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, description briefly enumerates parameters but adds no new meaning beyond what is in 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?

Clearly states the verb (Run + recompute), resource (script), and output (volume/surfaceArea/bbox). Distinguishes from siblings like evaluate_script by specifying inspection of a specific feature.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus siblings. Agent must infer usage from context; lacks alternatives or exclusions.

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

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

Annotations already confirm read-only and non-destructive behavior. The description adds valuable behavioral context: the tool returns an agent-facing inventory including mechanical review facts and a next-action prompt, and it 'makes random/floating geometry explicit,' which explains its effect on the program state without contradicting 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?

The description is two sentences with no wasted words. The first sentence front-loads the purpose and output, and the second adds precise usage guidance. Every sentence earns its place.

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

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

Given the tool has 3 optional parameters and no output schema, the description adequately details the return items (parts, bboxes, connectors, etc.) and usage context. It could be improved by mentioning error cases or required script validity, but it remains largely complete for an inspection tool.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description does not add additional details about parameters beyond what the schema provides; it only mentions 'kernelCAD script' which aligns with code/file parameters.

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

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

The description clearly states the tool evaluates a kernelCAD script and returns a specific assembly inventory with named parts, connectors, mates, etc. It distinguishes itself from siblings by focusing on physical assembly analysis and next-action prompts, which is not offered by sibling tools like validate_assembly or review_cad.

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 advises using this tool before design_loop or after a visual rejection, providing clear context for when it is appropriate. It does not list alternatives but directly mentions a sibling (design_loop) and a specific scenario (visual rejection), giving strong usage 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 detail beyond the annotations (readOnlyHint true) by specifying exactly what categories of functions and key sets are listed. It confirms no mutation, and there is no contradiction with 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?

The description is a single sentence that front-loads the main purpose. It is concise but slightly dense due to the listing of categories; a more structured approach (e.g., bullets) could improve readability, but it is effective.

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?

While the description explains what is listed, it does not describe the output format or structure. Since there is no output schema, the agent might benefit from knowing whether the result is a list of strings, objects, or something else. Additional detail on the return value would improve completeness.

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 input schema has no parameters (100% coverage), so baseline 4 applies. The description does not need to add parameter information, and it doesn't.

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 that the tool lists the script-runtime surface, enumerating specific categories like global functions, Shape methods, etc. This distinguishes it from sibling tools that list specific entities (e.g., list_features, list_edges).

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 directs the agent to use this tool to discover what is callable from a .kcad.ts script. However, it does not explicitly state when not to use it or name alternatives, though the context from sibling tools implies that for specific entity lists other tools should be used.

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 that the tool lists 'assembly intent' and specifics of what is included, providing useful behavioral context beyond 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?

Two sentences, no redundancy. First sentence conveys purpose and output scope, second sentence directs parameter usage. Efficient and front-loaded.

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

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

With no output schema, description adequately hints at return content (list of assembly components). Covers both input options but lacks details on pagination or limitations.

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 covers 100% with descriptions. Description adds the exclusivity rule ('Pass either { file } or { code }') which is not in the schema, improving semantics for tool invocation.

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?

Description clearly states the tool lists assembly intent from a kernelCAD script, enumerating specific items (assemblies, parts, connectors, etc.), and distinguishes from sibling tools that add or modify. The verb 'list' and resource are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Only instruction is to pass either file or code. No guidance on when to use this tool over siblings like list_constraints or list_mates, or exclusions.

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

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

Annotations already indicate read-only and non-destructive behavior. Description adds that it echoes the input list, which clarifies the tool's effect beyond 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?

Two sentences, no wasted words. Front-loads the core purpose and usage guidance efficiently.

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 simplicity (single optional parameter, no output schema), the description fully covers its functionality and intended use case.

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 0% schema coverage for the 'constraints' parameter, the description adds value by stating it echoes the provided constraint list, explaining the parameter's purpose.

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?

Clearly states it lists supported sketch constraint types and echoes the provided constraint list. Distinguishes from siblings like add_constraint and solve_sketch.

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 instructs to use before add_constraint or solve_sketch to discover vocabulary, providing clear context and alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds context: it's a 'tiny one-shot call' and that the canonical list is returned upfront, complementing inline hints. 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, front-loaded with the action, no wasted words. Every sentence adds value.

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

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

For a simple list retrieval tool with no parameters and no output schema, the description fully explains purpose, usage, and behavioral context. 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?

No parameters exist, so schema coverage is 100%. Baseline for 0 parameters is 4. Description doesn't add parameter info, but none is needed.

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?

Description clearly states 'Return the kernelCAD 26-code diagnostic catalogue with hint templates'. It uses a specific verb and resource, and distinguishes from sibling tools by being a catalogue retrieval utility rather than a geometric operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: 'useful for an agent that wants to pre-populate retry strategies'. It explains the tool's role relative to inline hints. No explicit exclusions, but the simple read nature makes it obvious when to use.

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, so the description adds only the return field list and the mutual exclusivity of file/code. This is useful but not extensive behavioral context beyond what annotations provide.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: purpose, usage context, parameter clarification. No fluff, front-loaded with the action and resource.

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 purpose, return values, usage, parameter semantics. Missing only a mention of error cases or performance, but for a read-only list tool with good annotations, this is sufficient.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are fully documented in schema. The description adds the critical insight that file and code are mutually exclusive (though not enforced in schema), which adds significant meaning 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?

Clearly identifies the tool's action (list) and resource (edges of a kernelCAD shape), and specifies the return fields. Distinguishes itself from sibling tools like list_faces and list_topology by focusing on edges.

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 advises using this tool to discover edges before fillet/chamfer operations, and clarifies the parameter choices (file vs code, optional query). Lacks explicit 'when not to use' or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it lists labels from two sources and includes source info, enhancing transparency without contradicting 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?

Two sentences: the first declares purpose, the second gives usage guidance. Every sentence is necessary and front-loaded without 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?

For a read-only listing tool with three optional parameters and no output schema, the description covers what the tool returns (labels with source) and its usage context, making it complete enough for an agent.

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 does not add meaning beyond the schema; it mentions script file types but repeats schema info.

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 that the tool lists user-applied labels visible in a script, specifying two sources (sketch-segment labels and creating-op faceLabels) and that results include source for disambiguation. This distinguishes it from sibling tools like list_faces.

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 provides context: 'Lets agents discover the label vocabulary on a shape before referencing labels in fillet/chamfer/shell.' This implies when to use it, but does not explicitly state when not to use it or mention alternatives.

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

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

Annotations (readOnlyHint=true, destructiveHint=false) already indicate a safe read operation. The description adds value by specifying the exact return fields (id, centroid, normal, etc.) and the mutual exclusivity of code and file inputs, which helps the agent understand expected behavior beyond the 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 remarkably concise: two sentences that efficiently communicate purpose, input requirements, output structure, and use case. Every sentence serves a clear function without 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?

Given the absence of an output schema, the description fully covers return values. It addresses all input parameters, their defaults (feature_id), and the optional query filter. The use case is stated, and the read-only annotation complements the description. No obvious gaps remain for an agent to select and invoke the tool 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 the description doesn't need to restate. However, it adds meaning by explaining the query object as 'FaceQuery filter (atZ, parallelTo, ofSurfaceType, etc)' and clarifying that feature_id defaults to the last returned shape—details that go beyond the schema's minimal descriptions.

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

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

The description clearly states the tool lists faces of a kernelCAD shape with optional filtering, specifies the returned fields (id, centroid, normal, surfaceType, area, label), and distinguishes it from siblings like list_edges or list_face_labels by focusing on face introspection for shell/face references.

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 provides a use case ('face introspection before shell/face references') and notes that either { file } or { code } should be passed, but it does not explicitly exclude alternatives or compare to sibling tools (e.g., list_face_labels, get_face_lineage). Some guidance is present but not comprehensive.

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. The description adds context by detailing the specific attributes returned, which is not covered by 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?

Two sentences, no wasted words. First sentence front-loads the purpose and return content; second sentence gives parameter guidance. Perfectly sized.

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

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

Given no output schema, the description lists the returned fields adequately. Does not mention edge cases (e.g., empty script) but provides enough for typical use.

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 covers all parameters with 100% description coverage. The description adds the nuance that the two parameters are mutually exclusive ('Pass either { file } or { code }'), which is not explicit 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?

Description clearly states the tool lists features from a kernelCAD script and enumerates the returned attributes (kind, id, params, inputs, transforms count, suppression). It distinguishes from sibling tools that add or list other entities.

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 specifies the parameter options ('Pass either { file } or { code }') but lacks guidance on when to use this tool versus alternatives, such as list_topology or get_shape_info.

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, and the description reinforces this with 'Read-only' and adds implementation detail ('reads arm.__mates()') and return format. 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: first states purpose, second adds implementation detail and structured return format. No unnecessary 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?

For a simple list tool with annotations, the description covers purpose, safety, and return format. Missing parameter documentation is a minor gap, but overall sufficient given low complexity.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'assembly' is not documented in the description, despite 0% schema coverage. The description mentions 'active assembly' which may confuse with the parameter. No additional meaning beyond the type.

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

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

The description clearly states the verb 'List' and resource 'mate records' with context 'on the active assembly'. It distinguishes from siblings like 'add_mate' and 'solve_mates' by being a read-only listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing mates and indicates it is read-only. However, it does not explicitly specify when to use this tool over alternatives or mention any prerequisites.

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 indicate readOnlyHint and destructiveHint. The description adds behavioral detail: returns face names based on feature type (box, cylinder, sphere/non-primitives). 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 concise sentences: first describes output, second tells how to invoke. Front-loaded and no unnecessary 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?

No output schema, but description covers the main outputs and behavior for different feature types. Adequate for a simple list tool, though order of face names is not specified.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only lists parameter names without explaining their semantics or how they affect the output. Minimal value added for 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 the tool lists canonical face names (differentiated by feature type) and total edge count. It distinguishes itself from siblings like get_face_lineage or list_faces by focusing on canonical names.

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 mentions passing optional parameters but does not explicitly state when to use this tool over alternatives like get_edges_of or list_face_labels. Usage context is implied but not formally guided.

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. The description adds output structure (uri, mimeType, text) and confirms no input, providing additional context beyond 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?

Concise: two main sentences plus a note on usage and input/output. No fluff, with key information front-loaded.

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

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

Fully describes purpose, output, and when to use it. For a simple lookup tool with no parameters and no output schema, this is 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?

No parameters exist, and schema coverage is 100%. The description confirms INPUT: none, meeting the baseline for zero-parameter tools.

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

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

The description clearly states the tool returns the kernelcad-authoring SKILL.md body, specifying its content (conventions for .kcad.ts scripts). It distinguishes itself from sibling tools by being a documentation lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use the tool (if client does not list resources) and provides an alternative resource read, making the usage context very clear.

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

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

Annotations already indicate readOnlyHint=true. The description adds ranking mechanism (BM25 over title/tags/keywords/trigger) and the empty return condition. 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?

Three sentences: action and return, usage guidance, edge case. Front-loaded with purpose, no fluff. Efficient and well-structured.

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 search tool with no output schema, the description sufficiently covers return format (top-k snippets), ranking, and empty case. Given the tool's simplicity, it is fully complete.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with good parameter descriptions. The description adds value by explaining how the query is used (natural-language, ranked by BM25) and the purpose of k beyond default/max.

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

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

The description clearly states the tool searches a cookbook for canonical pattern snippets, with specific verb 'Search' and examples of patterns like 'fillet-after-subtract'. It distinguishes from sibling lookup_authoring_skill by focusing on patterns, not authoring skills.

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 guidance on when to use ('when you need a canonical pattern') with concrete examples. Also tells the agent what to do if no results ('proceed without cookbook help'). Does not mention alternatives but the context is clear.

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

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

Annotations already provide readOnlyHint and destructiveHint. The description adds behavioral details: it lists 'current values, defaults, and metadata', which goes beyond annotations and informs the agent about the scope of output.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys purpose and constraints.

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 simplicity (no parameters, read-only, no output schema), the description fully covers the agent's need to understand what the tool does and its side effects.

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 input schema has 0 parameters, so schema coverage is 100%. With no parameters, the description need not explain them. Baseline 4 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?

The description clearly states the verb 'List', the resource 'parameters on active session', and the output includes 'current values, defaults, and metadata'. It also notes 'Read-only', distinguishing it from the sibling 'params_update' 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?

No explicit guidance is given on when to use this tool versus alternatives. The read-only nature is mentioned, but there is no discussion of when listing parameters is appropriate.

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?

Annotation contradiction: readOnlyHint=true while description claims mutation ('Edit... and re-lower'). Per guidelines, score 1 when description contradicts annotations. The description itself is transparent about behavior, but the contradiction undermines overall transparency.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no fluff, front-loaded with action. Could be slightly more structured but is efficiently concise.

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

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

Given no output schema, the description covers return values (updated shape, records, warnings), atomicity, and validation. Missing explanation of 're-lower' or prerequisites, but overall adequate for a moderately complex tool.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only says 'Edit one or more session parameters' without elaborating on the structure of the 'edits' array, name/value fields, or constraints. The description adds little 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?

The description clearly states the tool edits session parameters and re-lowers affected records, specifying validation and atomicity. It distinguishes this batch operation from sibling tools like set_param_value and params_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (for multi-param edits requiring re-lowering) but does not explicitly contrast with alternatives or state when not to use it. Some guidance is present via behavioral cues.

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 indicate readOnlyHint=true and destructiveHint=false, so the description adds valuable behavioral context: it declares the tool as side-effect-free, returns modified code plus diagnostics, and discloses a limitation (`asEdge: true` is deferred). This exceeds the minimum burden and aligns with 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?

The description is a single paragraph of three sentences, front-loading the primary action ('Insert a...call') and then elaborating with purpose and a key detail. Every sentence serves a distinct purpose with no 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?

Given the tool's complexity (7 parameters, 4 required, no output schema), the description covers the main operation, usage hints, side-effect nature, and diagnostic return. It provides sufficient context for an agent to understand inputs, expected behavior, and limitations.

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 marginal value by explaining that `curveExpression` is inserted verbatim as the `curve` field and notes the deferred status of `asEdge`. It does not significantly enhance understanding beyond the already-detailed schema descriptions.

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

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

The description clearly states that the tool inserts a `.projectCurve()` chained call into a kernelCAD script, and explains the operation: wrapping a 2D closed curve onto a 3D face. It distinguishes from sibling tools by focusing on code insertion for CAD scripting, which is unique among the listed 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?

The description provides usage context by mentioning pairing with `.extrude()` or `.cut()` for engraving logos, but does not explicitly state when not to use this tool or contrast it with alternatives such as `add_sketch_text` or `emboss_text`. Guidance is implied but not comprehensive.

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 context beyond annotations by specifying refusal to remove return statement and claiming side-effect-free, aligning with readOnlyHint=true.

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 concise sentences front-loading the core action, output, and constraints with no 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?

Fully covers behavior, output (modified code and diagnostics), and constraints (refuses return statement) despite no 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?

Explains that match uniquely identifies the line, adding nuance not in schema; schema already covers both parameters well.

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

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

The description clearly states the tool removes a single line from a kernelCAD script via substring match, distinguishing it from sibling tools like add_feature.

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?

Implicitly tells when to use (to remove a line) but does not explicitly state when not to use or mention alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context: the tool is deterministic, performs multiple checks (script evaluation, validation, interference), and returns a fitness verdict with repair modes. It does not contradict 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?

The description is a single paragraph that front-loads the main purpose and details the checks. It is comprehensive but not overly verbose; every sentence contributes to understanding the tool's functionality.

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 11 parameters and no output schema, the description lacks details about the return format of the fitness verdict. It mentions repairMode options but does not specify the structure, leaving some ambiguity for the agent.

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. The description does not add meaning beyond the parameter descriptions already in the schema; it only gives an overview of the tool's actions.

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

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

The description clearly states the tool runs a deterministic CAD review loop, listing specific checks (evaluate script, validate assembly, check mate connectors, etc.) and returns a mechanism fitness verdict. This distinguishes it from sibling tools like validate_assembly or inspect_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?

The description explains what the tool does but does not explicitly state when to use it versus alternatives. It implies usage for reviewing CAD designs, but no guidance on exclusion criteria or comparison with sibling tools like validate_assembly.

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 context beyond annotations by stating the return value (modified code as text plus diagnostics) and explicitly noting no side effects. Annotations already declare readOnlyHint=true, and the description is consistent without 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 sentences, front-loaded with purpose, no redundant information. Each sentence serves a distinct role: what it does, what it returns, and how to handle persistence.

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 3 required params and no output schema, the description adequately explains the return type and side-effect behavior. It could add details about diagnostics format or error handling, but it is sufficient for typical use.

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 description adds minimal extra meaning. It clarifies that param_name is the string literal argument to param(), which is a slight improvement over the schema 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 clearly states the verb (edit), resource (param() default value), and context (kernelCAD script). It distinguishes from siblings like params_list and params_update by specifying the exact action and return type.

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 explains that the tool has no side effects and that the caller must persist the code using file-write tools. This indicates when to use it and what the caller must do, though it does not explicitly contrast with sibling tools for batch updates.

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 discloses the return structure ({ status, poses, iterations? }) and explains pose serialization, adding value beyond the annotations (readOnlyHint=true, destructiveHint=false) by detailing the output format.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences) and front-loaded with the action and return type, containing no unnecessary 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?

While the return format is explained and the poses parameter is clarified, the assembly parameter is undocumented, and no error conditions or prerequisites are mentioned. For a tool with no output schema, the description is moderately complete but has clear gaps.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to the 'poses' parameter ('Optional poses overrides mate pose values by mate name'), but fails to describe the 'assembly' parameter, which has no schema description. With 50% schema coverage, the description partially compensates but leaves a gap.

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

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

The description clearly states the action ('Run the v0.6 mate-graph solver') and the resource ('on the active assembly'), with a specific verb and resource that distinguishes it from sibling tools like solve_sketch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives (e.g., solve_sketch) or when not to use it. The description simply states what it does without usage context.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds 'Side-effect-free', which reinforces the readOnly nature, but does not disclose additional behaviors like error handling, performance characteristics, or what happens with unsolvable constraints. Given the moderate annotation coverage, the description provides some value but not extensive behavioral context.

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 extremely concise: two sentences that front-load the core purpose and structure. No extraneous information or repetition. Every sentence adds value.

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

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

Given no output schema, the description clearly states the return format (solved entities plus original constraints). It also covers the required inputs and their types. However, it omits specific details about the kernelCAD constraint vocabulary (e.g., common constraint types), which might be needed for proper usage. Overall, it is sufficiently complete for a tool with good schema coverage and two parameters.

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 input schema descriptions for 'entities' and 'constraints' are basic. The description adds significant meaning by stating entities are POINT, LINE, and CIRCLE records, and constraints use kernelCAD vocabulary. This provides crucial context beyond the schema's generic descriptions, helping the agent construct valid inputs.

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 'Solve a 2D sketch constraint set' with a clear verb and resource. It specifies input and output structure (entities and constraints) and mentions entity types (POINT, LINE, CIRCLE) and constraint vocabulary, making the tool's purpose unambiguous. However, it does not explicitly differentiate from sibling tools like solve_mates, which might cause confusion for an AI agent choosing between 2D and 3D solving 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?

The description explains the tool is side-effect-free and what to pass/receive, providing context for use. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., solve_mates for 3D, add_constraint for adding constraints). The usage context is implied (2D sketch solving) but not explicitly stated, leaving ambiguity.

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 indicate read-only and non-destructive behavior. Description adds backend dispatching, accuracy honesty, per-feature confidence reporting, and caller API cost, providing full behavioral context.

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 well-structured sentences with no redundancy. Each sentence serves a purpose: primary function, backend details, accuracy, caller costs, and additional resources.

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?

Despite no output schema, description explains output format (normalized waypoints) and confidence. Covers all parameters, backend behavior, and integration with CAD workflows, making it complete.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and description adds significant meaning: explains backend enum values, default features behavior, image URL formats, and hints for vision-LLM usage.

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 'Trace pixel-space features from a reference photo into normalized [0..1] waypoints', with specific verb and resource, and distinguishes it from sibling CAD 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?

Explicitly describes three backends, default 'auto' selection logic, accuracy trade-offs, and that vision-LLM requires caller's API key. Also recommends pairing with a skill for mm conversion.

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, so the agent knows it is a safe read operation. The description adds behavioral context by noting it runs a validator and returns diagnostic codes for recovery, which goes beyond 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?

The description is extremely concise: one sentence plus a brief list of return fields. No unnecessary words, and key information is front-loaded.

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

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

The return structure is specified, but the parameter usage remains unexplained. Given the tool's simplicity (one parameter, no output schema), the description covers most aspects but leaves a notable gap in parameter documentation.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'assembly' has 0% schema description coverage, and the description does not clarify its purpose, meaning, or whether it is optional (since 0 required parameters). It only mentions 'on the active assembly', leaving ambiguity about the parameter role.

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

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

The description clearly states the tool validates the active assembly using mate-aware validator and specifies the return structure (status, diagnostics, partCount, jointCount). It distinguishes itself from siblings like inspect_assembly and list_diagnostic_codes by focusing on validation with mate awareness.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as inspect_assembly or list_diagnostic_codes. The description lacks explicit context for preferred use cases, leaving the agent without direction on selection criteria.

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. The description adds behavioral details: returns diagnostics of requested and upstream features in topological order, with per-code hints inline. No contradictions, and it supplements annotations well.

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 three sentences, front-loading the core action. It is fairly concise, but the last sentence ('Pass { file?, code?, feature_id? }') is somewhat awkward and could be integrated more naturally. Still, it overall avoids 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?

Given the complexity (walking upstream chain, returning diagnostics) and lack of output schema, the description explains the topological order and per-code hints reference. However, it does not clarify how the input parameters filter or combine, nor does it describe the diagnostic structure (beyond hints). This leaves gaps for an agent.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only lists the parameter names ('file', 'code', 'feature_id') with optional markers but provides no semantics, format, or usage examples. This minimal addition does not help the agent understand what each parameter means or how to use them.

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

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

The description clearly states the tool walks the upstream chain of a failing feature and returns diagnostics in topological order. It uses a specific verb ('walk') and resource ('upstream chain'), and the purpose is unique among siblings (most are create/list/modify).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for debugging failing features and instructs users to call list_diagnostic_codes for the full catalogue. It lists the expected input format but does not explicitly state when to avoid this tool or mention alternatives, which would improve guidance.

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