kernelcad

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

Description states 'side-effect-free', matching the destructiveHint=false annotation. Also explains the return value (modified source + diagnostics), adding 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 concise sentences plus a code snippet. Purpose is front-loaded, and every element is useful 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?

Given the output schema exists (not shown, but indicated), the description adequately covers the return value. The tool's complexity is moderate, and the description provides sufficient context 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 high (86%), so baseline is 3. The description provides a code snippet showing parameter usage, but does not add detailed semantics beyond what the schema already describes.

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

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

The description clearly states the tool adds a mate connector to a part, with a specific code insertion example. This distinguishes it from siblings like add_constraint or 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?

Provides clear context for when to use this tool (adding a mate connector to a part) and mentions side-effect-free. However, no explicit comparison or when-not-to-use guidance is given.

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

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

Description explicitly states 'Side-effect-free' which aligns with destructiveHint=false. It explains the tool returns the updated list, indicating no mutation of inputs. This adds valuable 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 redundant words. Front-loaded with purpose. Every sentence contributes necessary 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?

Given the tool has 2 parameters, nested objects, and output schema, the description covers purpose, usage pattern, and side-effect-free behavior. It does not detail output format, but output schema exists. Minor gap: could mention the output is a new list.

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 adds meaning by explaining the role of each parameter: 'constraints' as existing list (omit for empty), 'constraint' as the one to append. Also mentions 'validated' which hints at input validation.

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 'add' and resource 'sketch constraint to a list'. It distinguishes from siblings by specifying the domain (sketch constraint) and the action (appending to a 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 gives explicit context: 'Use this when you need to add a sketch constraint to a list.' It also provides usage pattern: 'pass { constraints, constraint } and receive the updated list.' It does not mention 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?

Beyond annotations, the description discloses precise insertion location ('immediately before the last top-level return'), side-effect-free behavior, failure behavior ('fails closed on its own missing required params'), and the exact declaration types inserted for each kind. This substantially enriches the agent's model of the operation.

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

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

The description is dense but well-organized: the purpose is front-loaded, followed by kind-specific bullets and downstream consumption. Every sentence contributes to correct invocation (semantics, defaults, failure mode, insertion point), with no fluff.

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 (10 params, nested objects, two authoring paths), the description covers when to use it, what each kind produces, how parameters are interpreted, where code is inserted, and how the result is consumed by sibling tools. The output schema exists, so return values need no extra explanation.

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?

Even though schema coverage is 100%, the description adds key meaning: tangent magnitude heuristic ('~ chord length'), curvature default effect (G1-only), NURBS defaults and optional knobs, and the G2 continuity semantics for the hermite path. This goes 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 states a specific action and resource: it authors a Curve3D into the user's .kcad.ts, with concrete use cases (body feature line, brow, spine rail, G2 blend). This clearly distinguishes it from sibling add_* tools, which target different objects (surfaces, features, connectors).

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 begins with an explicit 'Use this when you need a freeform/organic 3D curve' and lists concrete use cases, providing clear when-to-use context. It does not explicitly state when not to use it or name alternative tools, so it stops short of a 5.

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

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

The description adds behavioral details beyond annotations: insertion location, return of modified code plus diagnostics, and side-effect-free claim. Annotations indicate not read-only and not destructive, which aligns with the description's side-effect-free assertion (no permanent state change).

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, with a clear front-loaded usage statement. The third sentence about faceLabels and lookup_api is relevant but somewhat tangential; it could be separated. Overall, it is concise 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?

Given the presence of an output schema and annotations, the description covers key aspects: insertion logic, return value, side-effect-free nature, and an advanced tip. It could mention edge cases (e.g., no return statement) but is sufficient for typical usage.

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 descriptions for both parameters. The description adds an example for feature_code, clarifying the expected format and syntax beyond the schema's 'Single-statement source line to insert'. This provides practical guidance.

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 'insert' and the resource 'new feature line into a script', with precise location 'before the last top-level return statement'. This distinguishes it from sibling tools like add_constraint or add_part, which add different script elements.

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 begins with 'Use this when you need to insert a new feature line into a script', providing a clear use case. It also mentions side-effect-free behavior and a tip about faceLabels, but does not explicitly exclude when not to use it or compare to alternatives like add_connector.

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=false and destructiveHint=false, so the tool is not read-only and not destructive. The description adds that it 'durably edit source' and requires code and assembly_binding, plus states that each relation 'fails closed on its own missing required params', providing useful behavioral insight 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 concise (about 10 lines) with a clear front-loaded purpose statement and bullet-pointed breakdown of the three relation types. Every sentence adds value without redundancy. It is well-structured 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?

Given the tool's complexity (three distinct operations with many parameters), the description sufficiently covers all key aspects: the three relation types, their parameter shapes, common required params, and error behavior. An output schema exists so return values need not be described. The description stands alone as a complete guide for an AI 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 groups parameters by relation type (e.g., 'mate' expects { name, a, b, type, pose?, ... }), which adds structural meaning not explicit in the schema's conditional required blocks. It also explains that non-relation parameters are 'forwarded verbatim', clarifying 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's purpose: 'author a mate-graph relationship into the source'. It breaks down into three specific relation types (mate, coupling, transmission) with distinct parameter sets. This distinctively distinguishes it from sibling tools like add_constraint or add_connector.

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

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

The description opens with 'Use this when you need to author a mate-graph relationship', providing clear usage context. It mentions required parameters (code, assembly_binding) and the default relation. However, it does not explicitly compare to alternatives or state when not to use the tool.

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

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

Describes the side-effect-free nature ('caller persists the returned source') and explains that it returns modified source plus diagnostics. This goes beyond the annotations (destructiveHint=false, readOnlyHint=false) by clarifying the exact behavioral impact.

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: first states purpose, second explains the exact insertion, third clarifies side-effect-free. Every sentence earns its place with no redundant 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?

Given the complexity (6 parameters, all documented in schema) and the existence of an output schema, the description fully covers what the tool does and its constraints. The return behavior (modified source + diagnostics) is clearly stated.

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?

All 6 parameters have descriptions in the schema (100% coverage). The description does not add further meaning to individual parameters beyond what the schema provides, so 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?

Clearly states the verb 'add' and resource 'part to an assembly'. Describes the specific action of durably inserting a code line before the final return, distinguishing it from other add_* sibling 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 says 'Use this when you need to add a part to an assembly', providing clear context. Does not mention when not to use or alternatives, but the sibling tools are numerous and distinct.

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 are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the burden. It discloses that the tool mutates the chain anchor in place, returns modified code plus diagnostics from re-evaluation, is side-effect-free, and fails closed on missing required params. It also explains the exact injection point. This goes well beyond the annotations and gives the agent a complete behavioral picture.

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

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

The description is long but well-structured, with a front-loaded usage sentence followed by bullet-style breakdown of the three segment kinds. Every sentence conveys useful information without fluff. It is appropriately detailed for a tool with three variants and 14 parameters, though it could be slightly tightened without losing 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?

For a complex tool with three segment kinds, nested objects, and conditional requirements, the description is thorough: it covers the injection point, per-kind parameter constraints (including matching pen position), optional parameters, return value, side-effect behavior, and error handling. Nothing an agent needs to invoke it correctly is missing, especially given the rich input schema and 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?

Even though the schema has 100% description coverage, the tool description adds substantial semantic value: it explains each kind's behavior (e.g., spline interpolates through waypoints, tangents are normalized internally, hermite curvature defaults to G1), enforces constraints like points[0] matching the pen position, and clarifies optional parameters like tension, degree, weights, and knots. This goes far beyond the schema's field-level 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 appends a curved segment to an existing PathBuilder chain on a named chain_anchor variable, with three specific kinds (spline, nurbs, hermite). It gives concrete use cases (eyewear brow, ergonomic grip, sneaker midsole) and distinguishes itself from other 'add_*' siblings by focusing on path segments. The verb-resource pair is unambiguous.

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

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

The description explicitly says 'Use this when you need a freeform/organic 2D outline...' and specifies that the call is injected at the END of the chain before any .close(). It provides clear context for when to use it but does not explicitly mention alternatives or when not to use it. The guidance is strong, though it stops short of naming competing tools.

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

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

Discloses side-effect-free nature, return value (modified code + diagnostics), pattern implementation as cumulative boolean union, and face ref naming convention. Annotations are consistent (readOnlyHint false, destructiveHint false).

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 paragraph, front-loading the core purpose, then covering insertion behavior, returns, side-effects, and geometric notes. Slightly verbose but 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 tool's complexity (7 params, nested objects, output schema exists), the description covers return value, side-effect-free nature, pattern unit concept, geometric implications, and face ref naming. It is complete for correct agent usage.

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

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

Schema coverage is 86%, so the schema already documents most parameters. The description adds value by explaining the role of 'target', 'assign_to', and the return value, but does not re-iterate all schema details.

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 repeats a feature in a pattern by inserting a pattern call into a script. It distinguishes from siblings like add_feature (general feature addition) and flatten_pattern (different 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?

Explicitly says 'Use this when you need to repeat a feature in a pattern' and provides context on when each pattern kind is appropriate via the schema. Also gives guidance on additive vs subtractive features.

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 non-obvious behaviors: weights are honored for rational surfaces, trim keeps the largest imprinted piece, split returns a tuple, sew produces a watertight solid and emits open-shell diagnostics, and draft emits feature.draft.failed on invalid geometry. It also notes that returned surfaces produce no Shape until .thicken/.toShape() via add_feature, and that Shape/Curve3D cutters are deferred. This all goes beyond the sparse annotations and is consistent with them.

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

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

The description is long but appropriately structured: a purpose sentence followed by five bulleted modes, each with the generated call, required data, and edge-case behavior. The front-loaded opening and bullet hierarchy make it skimmable. Some verbosity is justified by the tool's 5 modes and 23 parameters, and no sentence is filler.

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

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

The description covers all five modes, specifying required data, defaults (tolerance, degree bounds), failure semantics (fails closed, open-shell, draft.failed), and the follow-up pipeline (add_feature for thickening/toShape). With an output schema present and annotations minimal, it provides all context an agent needs to select and invoke the correct path.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by grouping parameters into construction modes (e.g., controls/degree/weights/knots/periodic vs section_sketch_ids for nurbs), documenting boundary edge ordering and the 1e-6 mm coincidence constraint not present in the schema, and clarifying trim/split and continuity defaults. It doesn't restate every schema field, which is appropriate given the schema is rich.

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 immediately states the tool's purpose: 'Use this when you need an organic, freeform, or swept shape... authored as a NURBS Surface' and enumerates five concrete modes (nurbs, boundary, trim, sew, draft). It distinguishes itself from siblings by naming add_feature as the follow-up step and clarifying the surface-authoring/finishing domain.

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 opens with explicit usage context ('Use this when you need...') and provides conditional guidance per kind ('Pass either { controls, ... } or { section_sketch_ids }'). It also points to add_feature as the alternative for converting a surface to a Shape. However, it doesn't explicitly state when not to use the tool, such as for primitive geometry that belongs in add_part.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, meaning the tool modifies code but is not destructive. The description adds context about the default font, side-effect-free behavior, and return of modified code plus diagnostics, which enhances transparency 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 concise and well-structured, starting with a clear purpose then detailing modes. It avoids fluff but could be slightly more compact.

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

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

Given the tool's complexity (17 parameters, 2 modes, output schema exists), the description covers the main behaviors and parameter groups. However, it lacks explicit guidance on parameter dependencies or mutual exclusivity, 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?

Schema description coverage is 100% with clear descriptions for each parameter. The tool description adds narrative grouping by mode and clarifies defaults, but this adds limited value beyond the schema's already-detailed parameter descriptions.

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

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

The description clearly states the tool is for authoring text into a kernelCAD script, and distinguishes between two modes (sketch and emboss) with specific actions for each. This provides a clear verb+resource purpose and differentiates from sibling 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 explicitly explains when to use each mode (e.g., 'sketch' for chainable text, 'emboss' for engraved/raised features) and mentions failure modes. However, it does not provide explicit guidance on when not to use the tool or compare 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?

Beyond the annotations, it discloses the insertion location, regex-based binding validation, fast structured-error behavior, the orientation caveat, that it returns modified code plus diagnostics, and that it is side-effect-free. These details align with the annotations' readOnlyHint=false and destructiveHint=false.

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

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

The description is long but well-structured and front-loaded with the primary use case. It contains some redundancy with the schema, particularly around section constraints and binding types, but every major behavior is covered without excessive filler.

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

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

Given the tool's complexity, the description covers when to use it, what it inserts, where it inserts it, the result type, parameter constraints, validation behavior, orientation limitations, and side-effect profile. An output schema exists, so the return-value detail is not a gap.

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

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

Schema coverage is 100%, and the description largely restates what the schema already provides: binding types, strict t ordering, and the [0,1] span. It adds minor context about existing source variables and the resulting Shape, but this does not significantly raise the 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 states a specific verb and resource: insert a `variableSweep(spine, sections, opts?)` declaration into the .kcad.ts source before the last top-level return. It clearly distinguishes this from sibling tools by naming the target use case — an organic swept solid whose cross-section changes along its length.

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

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

It opens with an explicit trigger: 'Use this when you need an organic swept solid whose cross-section changes along its length' and gives concrete examples. However, it does not name alternative tools or state when not to use it, so it stops short of full routing guidance.

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

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

The description discloses that the tool 'Durably insert[s]' code, indicating a permanent modification, and returns 'modified source plus diagnostics.' This adds context beyond the annotations (which only indicate not read-only and not destructive). The description 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 two sentences, front-loaded with the usage directive, and every sentence adds value. It is concise and well-structured 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?

Given the tool has an output schema and is moderately complex (5 params), the description fully covers the purpose, usage, return value (modified source plus diagnostics), and behavioral context (checked by validation gates). It is complete for an AI agent to understand how to use the 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?

The input schema has 100% coverage with descriptions for all 5 parameters. The tool description does not add any additional explanation beyond what the schema already provides. Baseline 3 is appropriate as the schema does the heavy lifting.

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: 'declare a reachability target for a connector.' It specifies the action (insert a workspace target) and the resource (connector). This clearly distinguishes it from sibling tools like 'add_constraint' or 'add_connector'.

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

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

The description starts with 'Use this when you need to...', providing clear context for when to use the tool. It explains that workspace targets are checked by validation gates. However, it does not explicitly state when not to use it or mention alternatives, slightly reducing the 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 provide limited info (readOnly=false, destructive=false). Description adds extensive behavior: collision verification, non-blocking collision handling (artifact still written), environment prereq, and return structure. Contradicts none.

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?

Description is long but each sentence adds value. Front-loaded with purpose. Some redundancy (environment requirement repeated) but overall efficient 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?

Covers all aspects: purpose, parameters, environment, return format, behavioral nuances. With output schema present, description still adds return structure details. Complete for an 8-parameter tool.

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

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

Schema coverage is 100%, but description adds significant context: file parameter emphasizes no code mode, focus/hide explains mutual exclusivity and render-only semantics, frames_dir/output_path mutual exclusivity, verify_every union with keyframe sample set. Greatly enhances 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 'Use this when you need to render a script's animation timeline to a video.' It specifies capture of animationView({...}) to MP4 or PNG frames, with a clear verb-resource relationship. It distinguishes from sibling tools like render_preview by focusing on animation capture.

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 usage context: 'FILE ONLY: pass { file }' and 'no { code } mode.' Explains mutually exclusive options and environment requirements. Does not explicitly mention when not to use or alternatives, but the context is sufficiently 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?

The description discloses the multi-step behavioral flow: per-attempt review_cad calls, continuing past attempts with unresolved warnings, returning structured repair prompts, and optionally writing a Studio-compatible build record JSON. This adds meaningful context beyond the sparse annotations and does not contradict readOnlyHint=false or destructiveHint=false.

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

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

The description front-loads the exact use case and then compresses the workflow into one scannable sentence. Every clause contributes either to tool selection or invocation behavior, with no filler or redundancy.

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

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

For a complex 17-parameter orchestration tool, the description provides the essential high-level workflow and side-effect caveat while leaving parameter and return details to the rich schema and output schema. It could be slightly more explicit about alternatives and when not to use this tool, but it covers the main selection and invocation needs.

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 the schema already documents nearly all 17 parameters. The description adds high-level loop semantics and highlights the outputRecordPath build-record behavior, but it does not systematically explain individual parameters beyond what the schema provides. Baseline 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 a specific orchestration verb and resource: 'Run an agent CAD design loop over one or more attempt scripts.' It differentiates from the review_cad sibling by describing the loop semantics—reviewing each attempt, continuing past functional attempts with warnings, returning structured repair prompts, and optionally writing a build record.

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 opening 'Use this when you need to run a CAD design loop over multiple attempts' gives clear invocation context. It does not explicitly list alternatives or exclusion criteria, but naming review_cad as the per-attempt reviewer implies single-shot reviews should use review_cad instead.

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 goes well beyond the readOnlyHint/destructiveHint annotations: it states the tool is read-only and never touches the active session, explains body-pairing fallback rules, the unmatched-body error, verdict precedence, and the fail-open behavior for render. This is rich, non-obvious 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 long but dense and front-loaded; the core purpose appears in the first sentence. Some details, like the overlay PNG explanation and fail-open behavior, are verbose, but they earn their place given the tool's 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?

For a complex geometry-diff tool, the description covers input modes, matching rules, error conditions, the full output table, verdict precedence, render behavior, and side effects. The presence of an output schema means return-value structure does not need to be repeated, and nothing essential is left out.

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

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

Although the schema already documents all 7 parameters, the description adds meaning the schema cannot: it clarifies that params re-lower the baseline, that file/code/params are mutually exclusive modes, that undeclared param names fail with a useful message, and what render produces. This materially helps an agent select and fill arguments.

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 opens with a precise statement of what the tool does: tells you WHAT MATERIAL changed, not just how much. It names the sibling tool diff_scripts and contrasts against it, so an agent can distinguish this tool without inspecting schemas.

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

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

It explicitly says 'Use this when...' and identifies diff_scripts as the shallower alternative, explaining why volume deltas alone are ambiguous. It also covers the two usage modes — two-script diff and one-script param sweep — so the agent knows exactly which input shape fits which scenario.

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, but the description adds meaningful behavioral context: it is read-only, 'never touches the active session,' and returns specific agent-readable JSON including volume deltas, bbox deltas, mate-graph changes, and param changes. This goes beyond what the annotations alone 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?

The description is dense but well-organized, front-loading the use case and then adding output details and an edge case. Some repetition and detail could be trimmed, but every sentence contributes useful information for tool selection and invocation.

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 presence of an output schema and annotations, the description is complete: it covers primary use case, input pairing, output structure, edge-case behavior, and safety. An agent can confidently select and invoke this 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?

The input schema already has 100% description coverage for all four parameters earned high baseline. The description adds value by clarifying how the parameters pair: baseline via baseFile/baseCode and revision via file/code, plus the '(root)' pseudo-part for single-shape scripts. This semantic pairing is not fully 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?

The description states a specific verb ('diff') and resource ('two script versions') and explains it produces a 'structured geometric delta.' It clearly distinguishes itself from generic geometry tools by focusing on script versions with baseline and revision inputs.

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

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

It explicitly says when to use it: 'Use this when you need to see exactly what changed between two script versions' and 'Use after editing a script to verify exactly what changed physically before re-rendering.' It doesn't explicitly name alternatives or exclusions, but the context is clear enough to guide 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?

Annotations only cover readOnlyHint=false, openWorldHint=true, and destructiveHint=false, which are minimal. The description goes far beyond by explaining the deterministic, no-vision-model approach, the classification of line types, projection reading, dimension handling, the output format (script and ledger), the verification process (re-projection and fidelity verdicts), and failure modes (raster-only). It also clarifies that dimension values override measured lengths and how assumptions are logged. This adds substantial behavioral context that the annotations do not 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?

The description is dense but every sentence serves a purpose: it front-loads the use case, then explains the deterministic process, the output, verification, and error handling. It avoids fluff and doesn't repeat schema details unnecessarily. It is structured logically from what it does to how it works to outputs and exceptions, making it easy to scan.

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

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

For a complex tool with 6 parameters and no required ones, the description covers the core workflow, output format, verification behavior, and failure modes. Its mentions of output schema (though not detailed here) and the existence of a ledger and fidelity verdicts give a complete picture of what the agent will receive. It also tells the agent how to handle open facts (resolve_assumptions, set_param), which is crucial for follow-up. Nothing essential appears missing for correct invocation and interpretation.

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

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

Schema coverage is 100%, and the schema descriptions already explain each parameter well (e.g., 'path' as path to the PDF, 'verify' as evaluate and compare). The description adds value by clarifying the use of 'out' (writes ledger beside it) and the interaction between 'path' and 'pdfBase64' (inline vs. on-machine). It also implies 'projection' as an override, which the schema already states. Since schema covers parameters thoroughly, a baseline of 3 would apply, but the description's extra context on 'out' and the hosted server use-case earns a 4.

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 converts a 2D engineering drawing PDF into a CAD script, distinguishes from photo-based or raster tools by naming trace_from_image as the alternative. The verb 'convert' and the resource type (drawing PDF) are specific, and the description explicitly excludes scanned (raster-only) pages, which differentiates it from similar 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 states when to use this tool: when the reference is a 2D engineering drawing PDF with orthographic views, not a photo. It also gives a clear exclusion: scanned pages should use trace_from_image, and mentions resolving assumptions with resolve_assumptions and set_param for follow-up. This leaves no ambiguity about context 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 read-only/non-destructive safety, and the description adds substantial behavioral detail: dryRun skips OCCT lowering, DFM gates, and meshing; it leaves the active session untouched; the default mechanism-truth gate can force ok:false; and skipMechanismCheck is ignored in dry-run/non-assembly cases. This goes well beyond annotation coverage and contradicts nothing.

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

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

The description is dense but every clause earns its place: trigger, output contract, assembly caveat, input modes, dry-run tradeoffs, and follow-up workflow. It is front-loaded with the most decision-relevant information and contains no filler.

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

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

For a tool with multiple modes, an output schema, and assembly-specific behavior, the description covers when to call it, how to invoke it, what dry-run sacrifices, what the mechanism gate does, and what to do afterward. The output schema handles return-value detail, so nothing essential is missing.

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

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

The schema already covers all four parameters at 100%, so the baseline is 3. The description adds value by stating the file/code alternatives explicitly and explaining the practical consequences of dryRun — millisecond-level fast iteration, what it can and cannot catch — beyond the schema's brief field 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 names a specific verb and resource — 'run a kernelCAD .kcad.ts script' — and enumerates concrete outputs: pass/fail, feature count, diagnostics, and an assembly-scene mechanism verdict. This scope clearly separates it from generic siblings like verify, inspect, or query.

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

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

It opens with an explicit trigger ('Use this when you need to run a script and check it compiles') and includes workflow guidance to finish with a non-dry run before session-dependent tools. It does not explicitly name sibling alternatives or exclusion conditions, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=true, meaning no destructive behavior. The description adds details about the return format and the meaning of distance values, which goes beyond annotations. No contradiction detected.

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 well-structured sentences, each earning its place. The first sentence is a clear purpose statement, the second explains output, the third gives usage hints. Slightly verbose but remains efficient.

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 presence of an output schema and 100% parameter coverage, the description provides sufficient context: input relationships, output structure, usage hints, and a comparison to a sibling. Minor missing details about error conditions are acceptable.

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 documented. The description adds value by hinting that file and code are mutually exclusive ('either...or') and explaining that fieldName refers to an sdf.bind binding. This clarifies usage 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 samples a signed-distance field at a point, specifies the return object, and distinguishes it from the expensive sdf.materialize sibling. The verb 'sample' and resource 'signed-distance field' 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?

The description explicitly says when to use it (to verify SDF composition before materialization) and mentions the prerequisite of binding the SDF field. It does not list alternative tools among siblings but provides enough context to avoid misuse.

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

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

The annotations provide only basic hints (not read-only, not destructive, open-world). The description goes far beyond this: it explicitly states that STL exports run a watertight verify by default and that failures still write the file, it lists which exports write sidecar mesh files (urdf, sdf-gazebo, usd-isaac), it documents failure codes (export.mesh.not-watertight, export.part.not-found), and it specifies that 'All params except `target` are forwarded verbatim; each target fails closed on its own missing required params.' This is rich behavioral context that is not present in 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 long (about 340 words) but packed with necessary details for 12 formats and two targets. It is front-loaded with the core instruction and then organized in two clear blocks with bolded target names. The sentence on STL verify and failure modes is a bit dense, but every sentence adds required information. It earns its length given the complexity, though a shorter summary at the top and more bullet formatting could improve scannability. Still, it is well-structured for its size.

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 huge parameter count (10) and nested object schema, the description covers all critical usage aspects: target selection, required vs optional parameters per target, per-format nuances (meshes written, verify behavior, failure codes), and the interaction between `options.format` and top-level `format`. The output schema exists and is rich, and the description explains what happens when the export fails (file still written, error codes). Nothing an agent needs to decide whether to call this tool and how to fill parameters is missing, aside from trivial details that are already in the schema.

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

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

The schema description coverage is 100%, and the schema descriptions already explain each parameter's purpose. The description adds meaning by linking all parameters to their target-specific behavior (e.g., `output_path` for model vs part, `output_dir` for all parts, `no_verify` to skip watertight gate) and by describing the required vs optional status for each target. It also clarifies that `options` is a per-format bag and includes detailed semantics for svg-drawing annotations, sections, autoAnnotate, and joint drives. This is more valuable than a simple schema list, though some schema descriptions already cover basics, so the description adds moderate-high 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 starts with 'Use this when you need to export geometry to a file' and immediately introduces two distinct exporters selected by `target`, each with its own output format list, behavior, and file-writing details. It clearly differentiates from siblings like get_model_mesh (which fetches a mesh rather than writing files) and capture_animation (which records visual output). The resource (geometry/assembly) and action (export to file) are explicit, and the sub-modes are unambiguously specified.

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 when-to-use ('Use this when you need to export geometry to a file') and then for each target details the required parameters and failure modes. It names the main alternative for reading geometry (get_model_mesh) implicitly by focusing on file export, and it mentions `inspect` as an alternative for BOM data ('same numbers as inspect({ of: 'bom' })'). It also gives guidance on what not to do (e.g., for part export, unknown part names fail; for STL, watertight verify is default). Very strong usage routing.

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

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

Even with readOnlyHint=true and destructiveHint=false, the description adds meaningful behavioral context: it returns stored data, checks toolchain availability, provides an install command when needed, and never meshes, solves, or writes. These details go beyond the annotations and set accurate expectations.

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

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

The description is front-loaded with the use case and communicates all essential behavior in three sentences. There is no filler; the rationale about choosing a grade against real material data 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 an output schema, strong annotations, and a single optional parameter, the description fully covers what the tool returns, how to target a previous run, and what it will not do. An agent has enough information to decide when to call fea_summary instead of run_fea.

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

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

Schema description coverage is 100% and the single optional parameter is fully documented in the schema: a directory from a previous run_fea, omittable for toolchain/material info. The prose restates this without adding new parameter semantics, so the baseline 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 identifies a specific purpose: retrieving the stored summary of a previous run_fea, toolchain availability, and material data. It distinguishes itself from run_fea by stating that it does not solve or mesh and only reads stored results.

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

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

It opens with the exact condition 'Use this when you need a structural check's context without paying for a solve,' and explains that the same output_dir from a previous run_fea should be passed. It also explicitly lists what the tool never does, making the choice between fea_summary and run_fea 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, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: bundled ids resolve offline, non-bundled ids require partsBaseUrl, and the return value includes cache path and sha256 fingerprint. This explains the caching mechanism and external dependency, which annotations alone do not capture.

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 (four sentences) and front-loaded with the primary use case. Every sentence adds value: when to use, resolution logic, offline vs online behavior, and return format. No redundant or wasteful text.

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

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

The description provides enough information to use the tool for its main purpose, covering id/query resolution, bundled vs non-bundled, and return values. However, it leaves gaps: the roles of 'family', 'category', and 'standard' are unexplained, and it does not clarify whether id and query can both be provided or their interaction. Given the low schema coverage and 6 parameters, the description is adequate but not 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 description coverage is only 17% (only partsBaseUrl has a description). The description explains the roles of 'id' and 'query' (resolve an id or single-match query), but does not address 'family', 'category', or 'standard' parameters. These remain ambiguous—whether they are part of the query or separate filters is unclear. With low coverage, the description should have compensated by detailing all parameters, but it only covers two out of six.

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: to download a catalog part as a STEP file. It specifies the action (download/fetch) and the resource (catalog part STEP file), and distinguishes from siblings like find_part (search) and add_part (adding parts) by focusing on file download. The verb 'fetch' combined with 'download a catalog part as a STEP file' is specific and unambiguous.

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

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

The description provides clear context on when to use the tool: 'Use this when you need to download a catalog part as a STEP file.' It also explains the resolution mechanism (id vs single-match query) and the difference between bundled and non-bundled ids with partsBaseUrl. However, it does not explicitly exclude alternative tools (e.g., find_part for searching or add_part for placement) or provide when-not-to-use guidance, which would improve clarity.

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 readOnlyHint=true and destructiveHint=false, and the description does not contradict these. It adds behavioral details like token AND-combination and cross-facet filtering, exceeding 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 concise, with three sentences that front-load purpose, then explain filtering logic, then remote tier setup. 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?

Given the presence of an output schema, the description covers the main functionality: search, filtering, and remote option. It is fairly complete for a search tool, though more detail on each filter parameter 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?

With only 13% schema description coverage, the description partially compensates by mentioning 'fuzzy query' (query), 'faceted filters' (category, family, etc.), and 'source' enum. However, parameters like 'tag' and 'standard' are not explained, leaving gaps.

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 finds a part in the catalog using fuzzy query and faceted filters. It specifies the verb 'find' and resource 'part in catalog', and distinguishes from siblings like 'fetch_part' by describing the search 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 explicitly says 'Use this when you need to find a part in the catalog' and explains search behavior (AND-combine) and remote tier option. However, it does not specify when not to use it or mention alternatives like 'fetch_part'.

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

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

The description reinforces the read-only nature (consistent with readOnlyHint annotation) by describing the output as an unfolded pattern. It adds behavioral details such as the output format and bend limit. No contradictions 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 at two sentences, front-loading the use case. The phrase 'Slice 1: at most 2 bends' is slightly unclear and could be reworded for better clarity. Overall, it is efficient but has a minor clarity issue.

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 covers the core functionality and output, but it does not explain the term 'Slice 1', nor does it address edge cases like more than 2 bends or error scenarios. No information on prerequisites or permissions is provided. The presence of an output schema reduces the need for output details, but the description could be more complete.

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

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

Schema coverage is 0%, so the description must compensate. It explains that 'file' and 'code' are alternative input methods, and 'featureId' is optional to select a specific shape. However, it does not describe the expected formats of 'file' or 'code', nor does it clarify that all parameters are optional. This leaves some ambiguity.

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: to obtain the unfolded flat pattern of a bent sheet-metal part. It specifies the output format (Region with polylines, holes, bend lines, sketch plane) and a constraint (at most 2 bends). This distinguishes it from sibling tools that focus on adding features or 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?

The description tells when to use the tool ('when you need the unfolded flat pattern') and how to specify input (using 'file' or 'code', with optional 'featureId'). It implies a limitation to sheet-metal parts with up to 2 bends. However, it does not explicitly mention when not to use it or recommend alternatives from the sibling tool list.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false; description adds critical behavior: render is from server model not user camera, deterministic bytes are not stale, no OAuth for public/unlisted, private requires owner signed in. Also describes error behavior (never blank image, {ok:false,error,hint}).

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

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

Long but every paragraph carries a distinct operational constraint: camera independence, determinism, auth, output mode, error behavior. Front-loaded with purpose and sibling routing before low-level details. No filler.

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

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

For a render tool with output schema present, the description covers invocation, view semantics, auth prerequisites, update ordering, and failure mode. No missing operational detail an agent needs to call it correctly.

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

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

Schema coverage is 100% but description enriches semantics: explains default 'all' as a labeled 3×2 contact sheet with specific ordering, single view behavior, paths_only tradeoff, and slug-as-capability auth implications. Exceeds schema baseline.

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

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

States a specific verb+resource+output: 'Render a project's current model server-side and return it as an inline image.' Explicitly contrasts with open_in_studio and describes its niche (different view, contact sheet, slug-only). Easily distinguished from 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?

Explicitly says 'Prefer open_in_studio for the happy path' and gives conditions for this tool ('Use this tool for a different view... or when you only have a slug and are not publishing'). Also instructs to push with open_in_studio first after model changes.

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

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

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

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

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

Two sentences cover purpose, usage context, and auth. Front-loaded with the core action, zero wasted words.

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

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

Given the tool has a single parameter, annotations, and an output schema (not shown), the description fully covers purpose, usage context, auth requirements, and data type. No gaps identified.

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

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

Schema coverage is 100% with a clear description for 'slug'. Description adds context about slug's role in capability/authorization, which is valuable beyond the schema field description.

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

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

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

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

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

Explicitly states the tool is 'for the in-chat 3D viewer widget' and explains auth requirements based on slug visibility. Could be improved by stating when not to use (e.g., if only summary needed, use mesh_summary).

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

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

Annotations already mark readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context: returns full .kcad source and metadata, lists most recently updated first, requires OAuth for private/listing access, and notes that using the same slug with open_in_studio keeps the user's tab live.

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

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

Front-loaded with the core use case and organized into fetch vs. list modes. There is slight redundancy in mentioning OAuth twice (private projects and listing mode), but the description remains tight and readable.

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 sufficient for a single-parameter, read-only tool with an output schema. It covers modes, prerequisites, auth, ordering, and integration with open_in_studio; nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the slug parameter is described there, but the description adds real value beyond it: where the slug comes from (/p/<slug> links or prior listings), what happens if omitted, and the downstream requirement to reuse the same slug with open_in_studio.

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 a read-only tool for reopening or browsing saved kernelCAD Studio projects, with two explicit modes: fetch by slug or list the user's projects. It is easily distinguishable from siblings like open_in_studio and get_project_revision.

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

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

Gives explicit when-to-use guidance ('reopen a saved project or browse what the user has saved'), plus concrete routing: pass slug to fetch, omit slug to list. Auth requirements for private projects and listing mode are also stated, and the follow-up with open_in_studio is explained.

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 value by explaining that the source is immutable and that for private projects the owner's OAuth is required. It does not contradict annotations and adds practical context about capability-based access.

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 consists of three concise sentences, each adding essential information: definition, use case, and access details. No extraneous words; well-structured and front-loaded with the core purpose.

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 47 sibling tools (many mutations), the description fully covers when and how to use this read-only fetch tool. With an output schema present, return values need no further explanation. The description covers usage, access, and verification purpose completely.

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 descriptions for both parameters. The description adds meaning by specifying that slug and version come from open_in_studio and that slug acts as a capability for public projects, exceeding what the schema alone provides.

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 ('Fetch'), resource ('exact immutable .kcad source and parameters'), and context ('captured at a prior `open_in_studio` version'). It distinguishes this tool from siblings by focusing on read-after-write verification of a specific revision.

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 usage guidance: 'Use this to read-after-write verify a release' and details how to pass slug and version. It also explains access requirements for public vs private projects, covering when and for whom the tool 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?

Annotations declare readOnlyHint=true and destructiveHint=false, which already cover the read-only nature. The description adds some behavioral detail, such as for 'mass': 'density in kg/m^3, defaults to 1000 (water)' and flags when defaulted, and for 'bom': 'flag rows with no density source... instead of guessing.' However, it does not disclose edge cases like error behavior on invalid `of` values, or the fact that many subjects require a pre-existing script (file or code). Given annotations cover safety, a 3 is appropriate: it adds context but not extensive behavioral nuance.

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

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

The description is long (about 300 words) but is necessarily so given 23 subjects. It is front-loaded with the core purpose and the `of` parameter, then organizes each subject as a bullet-like line in the list. There is minimal redundancy; each line adds new information. However, the density of subjects might overwhelm some agents, but for a tool with such broad scope, this is acceptable. Slightly reducing detail per subject could improve conciseness, but it remains 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?

Given the tool's complexity (17 parameters, 23 enum values, nested objects), the description is remarkably complete. It explains each `of` value, key parameters like `stack` for section, `gyration_axis` for mass, and units (mm, kg/m^3). It also notes that most subjects accept `{ file | code }` and that params are forwarded verbatim. Since an output schema exists, return values are not the description's burden. Nothing critical for an agent to call this tool correctly is missing.

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

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

Schema coverage is 100%, so every parameter is documented in the schema with subject-specific descriptions (e.g., 'of:'section' — single slice position along `axis` (mm)'). The description adds a global note that parameters are 'subject-specific and forwarded verbatim' and provides in-text semantics for each `of` value, but the schema already describes parameters in detail. Thus the description adds marginal value over the schema, consistent with the baseline 3 for high coverage.

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

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

The description starts with a clear, specific purpose: 'read facts about a model.' It then enumerates 23 distinct subjects, each with a concise explanation of what facts are returned, e.g., 'assembly — physical assembly inventory (parts, bboxes, connectors, mates, disconnected solids).' This strongly distinguishes it from sibling mutation tools like add_feature or capture_animation, and even from read-ish tools like mesh_summary or diff_geometry by listing exactly what it inspects.

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 begins 'Use this when you need to read facts about a model,' clearly scoping its use to read-only inspection. It does not explicitly name alternatives, but the sibling list is full of write or specialized tools (add_*, solve_*, run_fea, render_preview), and the description implicitly contrasts by focusing exclusively on reading facts, leaving specialized reads (mesh_summary, diff_geometry) to their own subjects. The explicit 'All params except `of` are subject-specific' also guides 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?

Annotations already cover read-only/non-destructive behavior. The description adds meaningful context about what the tool exposes and the easy-to-miss NURBS capability, going beyond the annotations without contradicting them.

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

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

The description is front-loaded with the usage trigger and uses dense, purposeful enumeration of the API-surface categories. No sentence is wasted; even the caveat about NURBS surfacing has actionable 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 zero-parameter read-only lookup tool with an output schema, the description provides sufficient context: what it returns, when to invoke it, and a strategic caution about missing capabilities. Nothing is missing for an agent to call it correctly.

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

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

The input schema is empty, so there are no parameters to document; with 100% schema coverage the baseline is satisfied. The description focuses on output scope rather than parameter syntax, which is appropriate here.

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

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

The description clearly identifies a specific verb ('list') and resource ('kernelCAD script-runtime surface') and enumerates the categories included. It does not explicitly differentiate from sibling lookup tools like lookup_authoring_skill or lookup_cookbook, but the distinction is inferable from the content.

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 says 'Use this when you need to list...' and gives a workflow cue: call it before concluding that kernelCAD lacks a capability. It does not mention when to prefer sibling lookup tools or when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint and destructiveHint. Description adds the output format (uri, mimeType, text) and confirms no input needed, providing useful context beyond the structured fields.

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

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

Two sentences: first states purpose concisely, second gives usage guidance. No redundancy, front-loaded with core 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?

For a zero-parameter tool with safety annotations and output schema partially described, the description covers purpose, usage, and output format. Complete without 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?

No parameters exist, so baseline is 4. Description explicitly states 'INPUT: none', which reaffirms the schema. No further param explanation 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?

The description clearly states the tool returns the SKILL.md body for kernelcad-authoring conventions, specifying verb, resource, and content. It distinguishes from siblings like lookup_api and lookup_cookbook which are about different domains.

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 guidance: use this tool if the MCP client does not list resources, otherwise read the resource directly. Clearly states an alternative approach.

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 ranking method (BM25 over title/tags/keywords/trigger) and the empty result behavior, which go beyond the annotations (readOnlyHint, openWorldHint, destructiveHint). 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 concise, with a front-loaded purpose statement, and every sentence adds value. It includes examples and edge-case behavior without unnecessary detail.

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 is complete for a simple lookup tool: it explains the search mechanism, result handling, and use cases. With an output schema present, return value details are unnecessary.

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 covers 100% of parameters with descriptions. The tool description does not add significant new semantic meaning beyond what the schema already provides, so the baseline score 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 looks up canonical pattern snippets for CAD tasks, using a specific resource (kernelCAD cookbook). It distinguishes effectively from siblings like lookup_api and lookup_authoring_skill, which serve different purposes.

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 states when to use this tool ('when you need a canonical pattern snippet') and provides examples and behavior if no results are found ('proceed without cookbook help'). However, it does not explicitly mention when not to use it or suggest alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it is a 'tiny one-shot call' and that hints are also inline on every emitted diagnostic, providing additional behavioral context beyond annotations. 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 three sentences, front-loaded with the primary use case, and every sentence adds value without redundancy. It is concise 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?

Given the tool has no parameters, clear annotations, and an output schema, the description sufficiently explains the tool's purpose and usage context. It does not need to describe return values due to the output schema.

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

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

The tool has zero parameters, so schema coverage is 100%. According to the guidelines, 0 parameters yields a baseline of 4. The description does not add parameter info because none exist, which 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 provides the 'kernelCAD 26-code diagnostic catalogue with hint templates', using a specific verb 'look up' (implied) and resource 'diagnostic catalogue'. It distinguishes itself from siblings by focusing on the canonical list upfront, which is not offered by other 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 explicitly says 'Use this when you need the kernelCAD 26-code diagnostic catalogue' and mentions its utility for pre-populating retry strategies. While it does not list alternative tools or when not to use it, the context is clear enough for an agent.

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

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

Beyond the readOnly/destructive hints, the description discloses that meshing runs the full server-side OCCT pipeline, that params act as stateless slider recompute overrides, that raw vertex/index/normal arrays are never returned, and that ok becomes false when any feature fails to compile. This gives the agent a clear model of side effects and failure behavior.

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

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

The description is long but well-structured with clear INPUT/OUTPUT sections and every sentence adds value. The core behavior and output shape are front-loaded before usage guidance and alternatives, making it easy for an agent to scan.

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

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

Given the tool's moderate complexity, the output schema, and annotations, the description is complete: it covers input requirements, output structure, failure semantics, stateless behavior, what is intentionally not returned, and which sibling tools to use for different goals. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is already 100%, and the schema gives solid descriptions for source, fileName, and params. The prose adds useful operational nuance, such as fileName being diagnostic-only and params being applied as stateless overrides before meshing, but most parameter meaning is already 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 names a specific verb ('Mesh'), a concrete resource (a kernelCAD .kcad.ts source), and the exact deliverable (compact geometry summary with bounds and per-feature id/kind/triangleCount/bbox). It also positions itself against render-oriented siblings by explicitly saying raw arrays are never returned.

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

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

The description gives explicit use cases: inspect a model without a viewer, confirm part size/shape, check triangle counts, and verify every feature produced geometry. It also names alternatives for rendering (open_in_studio and get_latest_render), and explains when this tool is preferred over the legacy client worker.

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

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

Beyond the annotations, the description discloses the full pipeline: mesh welding/checking, plane/cylinder segmentation, extrusion-axis selection, slice fitting, rounding with recorded snaps, script emission, evaluation against the mesh, and fidelity comparison over up to 4 passes. It also spells out safety properties ('the mesh itself is never modified'), verdict thresholds, and the 'never silently dropped' policy for unmatched regions.

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

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

The description is long and dense, but every sentence earns its place: trigger, algorithm, output shape, fidelity criteria, limitations, and ledger workflow. It is front-loaded with the most decision-relevant facts. The lack of paragraph breaks makes it harder to skim, but for a tool this complex the length is justified.

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

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

With an output schema present and 100% parameter coverage, the description still supplies the missing behavioral context: return object fields, exact verdict conditions, refinement-pass behavior, unmatched-region handling, and the ledger-to-`resolve_assumptions` workflow. An agent has everything needed to call the tool, interpret the result, and know when the result is trustworthy.

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 already documents all 9 parameters at ~100% coverage, so the baseline is 3. The description adds meaningful context for `out` (sibling `.ledger.json`, param-name fact ids, `resolve_assumptions` workflow) and ties `minIoU`/`maxDeviationMm` directly into the verdict formula. It does not re-explain `maxTriangles`, `format`, or `weldToleranceMm`, but those are already well covered by 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 opens with a concrete trigger: 'Use this when you are handed an STL, OBJ or 3MF of a mostly prismatic mechanical part' and names the deliverable ('editable kernelCAD model'). It clearly distinguishes this tool from a faceted import or simple mesh inspection, and the title aligns with the described behavior.

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 first sentence gives an explicit 'Use this when' condition, and the description names the alternative it avoids: 'rather than a faceted lib.fromSTL import.' It also states boundary behavior: freeform surfaces, variable-radius blends, and chamfers are reported, not forced. However, it does not explicitly name sibling tools or state direct 'do not use this for X' exclusions, so the guidance is clear but not fully exhaustive.

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

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

Goes far beyond the annotations by disclosing status semantics (ok=true publish success; ok=false + meshStatus=failed as hard persist failure), async mesh behavior under CDN (meshStatus=building while OCCT finishes; the embed retries meshUrl), and agent behavioral constraints ('do not claim the viewer is ready', 'only then may you tell the user a preview was shown'). readOnlyHint=false is consistent with the described persist operation, so there is no contradiction. This is rich operational context annotations cannot convey.

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

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

The description is long (~270 words) but front-loaded with the core purpose in the first sentence and densely packed with actionable operational detail on status fields and async behavior. Minor redundancy exists between the early 'when the user wants to SEE or share' clause and the later trigger-phrase list, but given the tool's complexity, nearly 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?

For a complex tool with six parameters, an output schema, status fields, and asynchronous mesh persistence, the description covers the happy path, the hard-failure path, the building/async state, when to call, and parameter flows. Since an output schema exists, prose explanation of return values is unnecessary. No critical gap remains for an agent to call this 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% and the schema's own parameter descriptions are already detailed (code's evaluate_script reuse, slug's in-place update semantics, include_preview's cache and rasterization behavior). The description largely restates this guidance ('omit slug only for a new separate model', 'Pass include_preview:false to skip the rasterizer') without adding genuinely new parameter meaning, so the baseline 3 applies.

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

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

The first sentence states a compound but specific purpose — 'Save/publish the current kernelCAD model AND display it in one step' — naming the resource (kernelCAD model/project) and the three deliverables (persisted project, interactive viewer, PNG preview). It differentiates from siblings by explicitly excluding get_latest_render for the happy path and contrasting with evaluate_script, so an agent can tell this tool apart without opening schemas.

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

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

Gives explicit when-to-use conditions ('when the user wants to SEE or share the model'), concrete trigger phrases ('open it in Studio', 'let me see it', 'show me the model'), and a routine call pattern ('after you finish a build and after each meaningful revision'). It names the alternative tool to avoid (get_latest_render) and the exclusion condition ('the preview is already here when previewDelivered is true'). Nothing is left to inference.

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

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

Discloses the side-effect-free nature, the return shape ('modified code plus diagnostics'), the rejection of `asEdge: true`, and the face-normal wrapping behavior. This goes well beyond the annotations, which only set readOnly/destructive hints.

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 four purposeful sentences with the use case up front. Every sentence adds a distinct fact—entry point, source format, behavior/pairing, limitation, and side-effect profile—with no repetition of schema boilerplate.

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 code-rewriting tool with seven parameters, this description covers the when, the how, the return type, the side-effect profile, and a key unsupported edge. The rich schema and output schema fill remaining parameter-level details, so nothing an agent needs for correct invocation is missing.

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

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

The input schema already documents every parameter at 100% coverage. The description adds useful context by explaining the underlying `source` wire format and clarifying that `commands` must form a closed path, which is extra confidence beyond the schema's enum and example.

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

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

Opens with a concrete action—'wrap a 2D closed curve onto a 3D face'—and names the exact API call (`<shape>.projectCurve`). The 'chained call into a kernelCAD script' and 'returns modified code plus diagnostics' description separates it from sibling modeling tools like add_curve or add_surface.

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 when you need...' and gives a clear non-goal: open-wire projection with `asEdge: true` is not implemented and rejected at edit time. It even provides the composition pattern with `.extrude(d)` / `.cut(...)`, so the agent knows when and how to chain it.

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