kernelCAD

Run Design Loop

design_loop

Idempotent

Use this when the goal is complex / production / enclosure / gearbox / robot-arm / multi-body, or when you need evaluate→review/verify→revise until green. PREFERRED over one-shot evaluate_script+open_in_studio for Adam-level parts. Runs a CAD design loop over attempt scripts: review_cad each attempt, continue past functional attempts with unresolved warnings, return repair prompts (nextActionPrompt) plus structured revisionAssist (suggestedPatches / autoApplied.suggestedCode for repairable feature failures; cookbook steers for stacked-primitive toys). Stop on ok or convergence.escalate. To pick among N alternative candidates for one goal without a judge, pass them all as attempts with consensus:true (geometric medoid selection). Optionally write a Studio build record JSON.

Input Schema

Name	Required	Description
`goal`	Yes	Original user design goal. Fed into every review_cad repair prompt.
`assembly`	No
`attempts`	Yes	Ordered design attempts. Each item is { id?, title?, file? OR code?, visualReview? } — provide file or code (at least one). File attempts can be replayed by Studio build records.
`consensus`	No	Best-of-N by geometric consensus. When true, attempts are N independent candidates for the SAME goal (not a repair sequence): all are reviewed (stopOnPass ignored), all scripts are executed, candidates without a valid solid are dropped, and the candidate whose geometry agrees most with the others (medoid by symmetric Chamfer distance, same model frame) is selected. Ties go to more gates passed, then the shorter script. Returns consensus { chosenIndex, chosenAttemptId, scores, distances, reason }; ok / finalAttemptId / nextActionPrompt describe the selected candidate. Default false.
`autoRevise`	No	When true (default), failing attempts with repairable feature diagnostics (boolean miss, oversized fillet, …) run bounded repair_script and attach revisionAssist.suggestedPatches / autoApplied.suggestedCode. Set false to skip the extra repair pass (hints-only). Does not autonomously rewrite full CAD models.
`epsilonMm3`	No	Forwarded to review_cad.
`stopOnPass`	No	Stop after the first attempt that is functional and passes the quality gate. Default true.
`recordTitle`	No	Optional title for the build record.
`requirements`	No	Call-time external requirements ([{ name, predicate }]) every attempt is graded against, in the same ledger as script require(). Predicate shape: { metric, a?, b?, op, limit, tolerance?, density? }; operands: { kind: body \| faces \| edges \| part, ref, query? }. A failing or not-evaluated requirement blocks the attempt even with no expert geometry.
`combinatorial`	No	Sample all 2^N limit-corner combinations across mates with declared limits. Capped at 8 mates with limits; combine with samplesPerMate for both interior coverage and worst-pose detection. Default false.
`samplesPerMate`	No	Pose-envelope samples per declared-limit mate. 1 (default) = corners only; >=3 adds uniform interior points between min and max. Total samples per non-locked mate = samplesPerMate.
`trackConnectors`	No	Connector refs to track across sampled poses.
`outputRecordPath`	No	Optional JSON path to write a Studio-compatible build record.
`preserveInterfaces`	No	External mates, connector refs, part names, or behavioral interfaces the agent must preserve between attempts.
`allowReviewWarnings`	No	Warning diagnostic codes the original prompt explicitly allows. Other review warnings keep the loop iterating even if review_cad is functionally ok.
`includeInterference`	No	Forwarded to review_cad. Default true.
`includePoseEnvelope`	No	Forwarded to review_cad. Default true.
`requireVisualReview`	No	Require screenshot-backed visualReview with structured checks before accepting an attempt. Default true; set false only for explicit non-visual batch checks.
`requirePhysicalAcceptance`	No	Require declared physicalUseCase common-pose reachability and pose-bound quasi-static certification before accepting an attempt. Design-loop also enables this automatically when an attempt script calls physicalUseCase(...).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 25, 2026

addedInput schema / properties / requirements

Added value: +{
+  "description": "Call-time external requirements ([{ name, predicate }]) every attempt is graded against, in the same ledger as script require(). Predicate shape: { metric, a?, b?, op, limit, tolerance?, density? }; operands: { kind: body | faces | edges | part, ref, query? }. A failing or not-evaluated requirement blocks the attempt even with no expert geometry.",
+  "items": {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  "type": "array"
+}

Changed3 schema fields changedOct 24, 2026

removedInput schema / properties / bodyLikeness

Removed value: -{
-  "description": "When likenessProfile=automotive: body_bbox (required for gate), wheels, cabin_bbox, still_verdicts. Missing body_bbox fails with reference.likeness.gate-required. Stills may also come from visualReview.checks.",
-  "properties": {
-    "body_bbox": {
-      "type": "object"
-    },
-    "cabin_bbox": {
-      "type": "object"
-    },
-    "length_axis": {
-      "enum": [
-        "x",
-        "y"
-      ],
-      "type": "string"
-    },
-    "require_stills": {
-      "type": "boolean"
-    },
-    "still_verdicts": {
-      "items": {
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "wheels": {
-      "items": {
-        "type": "object"
-      },
-      "type": "array"
-    }
-  },
-  "type": "object"
-}

removedInput schema / properties / gripperAperture

Removed value: -{
-  "description": "Optional gripper aperture request forwarded to review_cad.",
-  "type": "object"
-}

removedInput schema / properties / likenessProfile

Removed value: -{
-  "description": "When 'automotive', require organic-body still checks on visualReview AND the body-likeness publish gate (pass bodyLikeness or stills on checks). Attempts stay non-ok until publishReady. Final open_in_studio must pass likeness_profile:'automotive' (server hard-gates success).",
-  "enum": [
-    "automotive"
-  ],
-  "type": "string"
-}

Changed2 schema fields changedOct 11, 2026

removedOutput schema / properties

Removed value: -{
-  "attempts": {
-    "description": "Per-attempt review results (includes revisionAssist when failed).",
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "convergence": {
-    "additionalProperties": true,
-    "description": "Present when trailing failures share a signature (escalate).",
-    "type": "object"
-  },
-  "finalAttemptId": {
-    "type": "string"
-  },
-  "goal": {
-    "description": "Echoed design goal.",
-    "type": "string"
-  },
-  "nextActionPrompt": {
-    "type": "string"
-  },
-  "ok": {
-    "type": "boolean"
-  },
-  "outputRecordPath": {
-    "type": "string"
-  },
-  "record": {
-    "additionalProperties": true,
-    "description": "Studio-compatible build record (when requested).",
-    "type": "object"
-  },
-  "recordUrl": {
-    "type": "string"
-  },
-  "revisionAssist": {
-    "additionalProperties": true,
-    "description": "Structured revision assist from the last failing attempt: hints, suggestedPatches (AST diffs), optional autoApplied.suggestedCode when repair_script cleared a repairable diagnostic. Honest scope — not full autonomous CAD rewrite.",
-    "type": "object"
-  }
-}

removedOutput schema / required

Removed value: -[
-  "ok",
-  "goal",
-  "attempts"
-]

Changed1 schema field changedSep 28, 2026

addedInput schema / properties / consensus

Added value: +{
+  "description": "Best-of-N by geometric consensus. When true, attempts are N independent candidates for the SAME goal (not a repair sequence): all are reviewed (stopOnPass ignored), all scripts are executed, candidates without a valid solid are dropped, and the candidate whose geometry agrees most with the others (medoid by symmetric Chamfer distance, same model frame) is selected. Ties go to more gates passed, then the shorter script. Returns consensus { chosenIndex, chosenAttemptId, scores, distances, reason }; ok / finalAttemptId / nextActionPrompt describe the selected candidate. Default false.",
+  "type": "boolean"
+}

Changed4 schema fields changedSep 25, 2026

addedInput schema / properties / autoRevise

Added value: +{
+  "description": "When true (default), failing attempts with repairable feature diagnostics (boolean miss, oversized fillet, …) run bounded repair_script and attach revisionAssist.suggestedPatches / autoApplied.suggestedCode. Set false to skip the extra repair pass (hints-only). Does not autonomously rewrite full CAD models.",
+  "type": "boolean"
+}

changedOutput schema / properties / attempts / description

Previous value: -"Per-attempt review results."New value: +"Per-attempt review results (includes revisionAssist when failed)."

addedOutput schema / properties / convergence

Added value: +{
+  "additionalProperties": true,
+  "description": "Present when trailing failures share a signature (escalate).",
+  "type": "object"
+}

addedOutput schema / properties / revisionAssist

Added value: +{
+  "additionalProperties": true,
+  "description": "Structured revision assist from the last failing attempt: hints, suggestedPatches (AST diffs), optional autoApplied.suggestedCode when repair_script cleared a repairable diagnostic. Honest scope — not full autonomous CAD rewrite.",
+  "type": "object"
+}

Changed2 schema fields changedSep 24, 2026

addedInput schema / properties / bodyLikeness

Added value: +{
+  "description": "When likenessProfile=automotive: body_bbox (required for gate), wheels, cabin_bbox, still_verdicts. Missing body_bbox fails with reference.likeness.gate-required. Stills may also come from visualReview.checks.",
+  "properties": {
+    "body_bbox": {
+      "type": "object"
+    },
+    "cabin_bbox": {
+      "type": "object"
+    },
+    "length_axis": {
+      "enum": [
+        "x",
+        "y"
+      ],
+      "type": "string"
+    },
+    "require_stills": {
+      "type": "boolean"
+    },
+    "still_verdicts": {
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "wheels": {
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

changedInput schema / properties / likenessProfile / description

Previous value: -"When 'automotive', also require organic-body still checks: side-body-over-wheels, side-cabin-aft, rear-haunch, ortho-proportions-vs-reference. Pair with verify({ check: 'body-likeness' }) before open_in_studio."New value: +"When 'automotive', require organic-body still checks on visualReview AND the body-likeness publish gate (pass bodyLikeness or stills on checks). Attempts stay non-ok until publishReady. Final open_in_studio must pass likeness_profile:'automotive' (server hard-gates success)."

Changed1 schema field changedSep 24, 2026

addedInput schema / properties / likenessProfile

Added value: +{
+  "description": "When 'automotive', also require organic-body still checks: side-body-over-wheels, side-cabin-aft, rear-haunch, ortho-proportions-vs-reference. Pair with verify({ check: 'body-likeness' }) before open_in_studio.",
+  "enum": [
+    "automotive"
+  ],
+  "type": "string"
+}

Changed1 schema field changedSep 21, 2026

addedInput schema / properties / requirePhysicalAcceptance

Added value: +{
+  "description": "Require declared physicalUseCase common-pose reachability and pose-bound quasi-static certification before accepting an attempt. Design-loop also enables this automatically when an attempt script calls physicalUseCase(...).",
+  "type": "boolean"
+}

Changed5 schema fields changedJul 18, 2026

changedInput schema / properties / attempts / description

Previous value: -"Ordered design attempts. Each item is { id?, title?, file? or code?, visualReview? }. File attempts can be replayed by Studio build records."New value: +"Ordered design attempts. Each item is { id?, title?, file? OR code?, visualReview? } — provide file or code (at least one). File attempts can be replayed by Studio build records."

addedInput schema / properties / attempts / items / anyOf

Added value: +[
+  {
+    "required": [
+      "file"
+    ]
+  },
+  {
+    "required": [
+      "code"
+    ]
+  }
+]

addedInput schema / properties / attempts / items / properties / code / description
```
Added value: +"Inline kernelCAD script source. Provide file or code."
```
addedInput schema / properties / attempts / items / properties / file / description
```
Added value: +"Path to a .kcad.ts script on disk. Provide file or code."
```

changedInput schema / properties / attempts / items / properties / visualReview / description

Previous value: -"Evidence from the reviewing agent after rendering/opening screenshots. Accepted reviews must include screenshotPath, concrete findings, and all required checks passing."New value: +"Optional. Evidence from the reviewing agent after rendering/opening screenshots. Accepted reviews must include screenshotPath, concrete findings, and all required checks passing."

Changed1 schema field changedJun 15, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "attempts": {
+      "description": "Per-attempt review results.",
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "finalAttemptId": {
+      "type": "string"
+    },
+    "goal": {
+      "description": "Echoed design goal.",
+      "type": "string"
+    },
+    "nextActionPrompt": {
+      "type": "string"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "outputRecordPath": {
+      "type": "string"
+    },
+    "record": {
+      "additionalProperties": true,
+      "description": "Studio-compatible build record (when requested).",
+      "type": "object"
+    },
+    "recordUrl": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "ok",
+    "goal",
+    "attempts"
+  ],
+  "type": "object"
+}

Changed1 schema field changedJun 7, 2026

changedInput schema / properties / attempts / items / properties / visualReview / properties / checks / description

Previous value: -"Required checklist entries: main-object-count, proportions-match-reference, required-visible-features, no-stray-or-floating-geometry, canonical-views-physically-coherent."New value: +"Required checklist entries: main-object-count, proportions-match-reference, required-visible-features, no-stray-or-floating-geometry, attachment-plausibility, semantic-orientation-alignment, device-depth-and-construction, canonical-views-physically-coherent."

First observedMay 25, 2026

TDQS

A3.9/5.0

Behavior3/5

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

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

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

Conciseness2/5

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

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

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

Completeness4/5

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

An output schema exists, so return values need no explanation, and annotations plus a 95%-described schema carry the parameter details. For a 19-parameter orchestration tool the description still conveys the loop's stop conditions, consensus mode, and repair-prompt contract. Only failure-path behavior and how attempts are ordered/aborted is left unstated.

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

Parameters3/5

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

Schema coverage is 95%, so the schema documents nearly every one of the 19 parameters and the baseline is 3. The description adds one genuinely extra piece of semantic intent for consensus:true (geometric medoid selection when picking among N candidates for the same goal) and the autoRevise hint-vs-patch distinction. That is marginal added value over an already-complete schema, not enough to lift it.

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

Purpose5/5

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

Specific verb+resource ('Runs a CAD design loop over attempt scripts') with the loop's core contract stated: review each attempt, continue past functional attempts with unresolved warnings, return repair prompts. It explicitly distinguishes itself from one-shot alternatives (evaluate_script+open_in_studio), so an agent can route correctly without opening any schema.

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

Usage Guidelines5/5

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

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

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

All kernelCAD tools Inspect

Try in Browser

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.