kernelcad

Run Design Loop

design_loop

Use this when you need to run a CAD design loop over multiple attempts. Run an agent CAD design loop over one or more attempt scripts: review each attempt with review_cad, continue past functional attempts that still have unresolved review warnings, return structured repair prompts, and optionally write a Studio-compatible build record JSON for visual replay.

Input Schema

TableJSON 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.
`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.
`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.
`gripperAperture`	No	Optional gripper aperture request forwarded to review_cad.
`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

TableJSON Schema

Name	Required	Description
`ok`	Yes
`goal`	Yes	Echoed design goal.
`record`	No	Studio-compatible build record (when requested).
`attempts`	Yes	Per-attempt review results.
`recordUrl`	No
`finalAttemptId`	No
`nextActionPrompt`	No
`outputRecordPath`	No

Schema Changelog

Changes observed during successful MCP inspections.

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

A4.2/5.0

Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

All kernelcad tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.