kernelCAD

Run Structural FEA

run_fea

Use this when you need to know whether a part will hold a load. Runs a linear-static structural study and returns evidence — peak von Mises stress (MPa), peak displacement (mm), the minimum safety factor against the material yield (taken away from the clamp-singular edges of the fixed faces; the raw clamp-edge peak is reported separately as peakAtSupportMPa), per-region hot spots named by @kc[...] face ref, mesh trust flags, an equilibrium residual, and (CalculiX only) stress-heatmap PNG paths. The study is EITHER declared in the script with shape.feaStudy({ material, fixed, loads, meshSize?, minSafetyFactor? }) OR passed on the call against the shape the script returns: { code: 'return box(100, 20, 10);', material: 'aluminum-6061', fixed: { atX: 0 }, loads: [{ faces: { atX: 100 }, force: [0, 0, -200] }] }. Faces are a FaceQuery ({ atX | atY | atZ, byNormal: 'Z', ofSurfaceType, near: [x,y,z], ... }; with near it names the ONE matching face nearest the point), a face label ('top', 'bottom', 'left', 'right', 'front', 'back'; it must name ONE face — after a boolean 'top' can be several, which is an error listing them) or an @kc[...] ref. Force is the TOTAL [Fx, Fy, Fz] in N on those faces (a scalar force + direction is accepted). Materials: mild-steel, aluminum-6061, pla, petg, abs, nylon (aliases steel, aluminum), or { E, nu, yield } in MPa. Solver (solver, default 'auto'): CalculiX + gmsh quadratic tets when that toolchain is installed; otherwise the built-in in-process voxel solver (8-node incompatible-mode bricks), which needs nothing installed and is marked summary.solver 'in-process-voxel' with trust.meshTrusted false — an estimate (accurate for prismatic bending, approximate at curved faces and notches), never a verified pass. solver: 'calculix' fails up front with fea.solver.unavailable and the install command when the toolchain is absent. Also: study (a declared study name; default the last), output_dir (keeps the deck / summary JSON), mesh_size (mm, overrides the study for this run), heatmaps: false for a numbers-only run. CalculiX mesh refinement is automatic: when the stress is untrusted only because the solver's error estimate is high, it re-solves once at 0.75x the element size (inside the element budget), with summary.refinement listing each pass. refine: false solves once.

Input Schema

Name	Required	Description
`code`	No	Inline kernelCAD script source (mutually exclusive with file).
`file`	No	Path to a .kcad.ts script declaring at least one feaStudy. Hosted server: cannot read files from your machine — pass `code`, or `project:<slug>` for a saved project.
`fixed`	No	Inline study: faces held fixed — a FaceQuery like { atX: 0 }, a face label like 'bottom', or an @kc[...] ref.
`loads`	No	Inline study: loads, each { faces, force: [Fx, Fy, Fz] } — total force in N on those faces.
`study`	No	Name of the declared study to run; defaults to the last declared one.
`refine`	No	One automatic finer pass (0.75x element size) when the stress is untrusted, inside the element budget (default true). false: one solve at mesh_size.
`solver`	No	'auto' (default): CalculiX when installed, else in-process. 'calculix': require it. 'in-process': always the built-in voxel solver.
`heatmaps`	No	Render stress heatmap PNGs (default true).
`material`	No	Inline study: material grade name (e.g. 'aluminum-6061') or { E, nu, yield } in MPa.
`mesh_size`	No	Target element size in mm, overriding the study for this run.
`output_dir`	No	Directory for the solver deck, results, summary JSON and heatmap PNGs.
`mesh_timeout_ms`	No	Wall-clock budget for meshing (default 120000).
`solve_timeout_ms`	No	Wall-clock budget for the solve (default 300000).
`min_safety_factor`	No	Inline study: required minimum safety factor; below it the call fails with fea.safety-factor.below-min.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 19, 2026
- addedInput schema / properties / fixed / type
```
Added value: +[
+  "string",
+  "object"
+]
```
- addedInput schema / properties / material / type
```
Added value: +[
+  "string",
+  "object"
+]
```

Changed6 schema fields changedOct 16, 2026

addedInput schema / properties / fixed

Added value: +{
+  "description": "Inline study: faces held fixed — a FaceQuery like { atX: 0 }, a face label like 'bottom', or an @kc[...] ref."
+}

addedInput schema / properties / loads

Added value: +{
+  "description": "Inline study: loads, each { faces, force: [Fx, Fy, Fz] } — total force in N on those faces.",
+  "items": {
+    "type": "object"
+  },
+  "type": "array"
+}

addedInput schema / properties / material

Added value: +{
+  "description": "Inline study: material grade name (e.g. 'aluminum-6061') or { E, nu, yield } in MPa."
+}

addedInput schema / properties / min_safety_factor

Added value: +{
+  "description": "Inline study: required minimum safety factor; below it the call fails with fea.safety-factor.below-min.",
+  "type": "number"
+}

addedInput schema / properties / solver

Added value: +{
+  "description": "'auto' (default): CalculiX when installed, else in-process. 'calculix': require it. 'in-process': always the built-in voxel solver.",
+  "enum": [
+    "auto",
+    "calculix",
+    "in-process"
+  ],
+  "type": "string"
+}

changedInput schema / properties / study / description

Previous value: -"Name of the study to run; defaults to the last declared one."New value: +"Name of the declared study to run; defaults to the last declared one."

Changed2 schema fields changedOct 11, 2026

removedOutput schema / properties

Removed value: -{
-  "artifacts": {
-    "additionalProperties": true,
-    "description": "Absolute paths of the BREP geometry handoff, .inp deck, .frd results and mesh JSON, for hand reproduction.",
-    "type": "object"
-  },
-  "diagnostics": {
-    "description": "fea.* diagnostics raised by the run.",
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "error": {
-    "type": "string"
-  },
-  "errorCode": {
-    "type": "string"
-  },
-  "images": {
-    "description": "Absolute PNG paths of the rendered stress heatmap.",
-    "items": {
-      "type": "string"
-    },
-    "type": "array"
-  },
-  "legend": {
-    "description": "Heatmap colour bands { color, fromMPa, toMPa } — the scale the PNGs are drawn on.",
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "ok": {
-    "description": "False when the study violated its declared minSafetyFactor, a selector did not resolve, or the solver toolchain is missing.",
-    "type": "boolean"
-  },
-  "out_dir": {
-    "description": "Directory holding the summary JSON, solver deck and heatmap PNGs.",
-    "type": "string"
-  },
-  "summary": {
-    "additionalProperties": true,
-    "description": "Solved evidence: maxVonMisesMPa, maxVonMisesAt, maxDisplacementMm, maxDisplacementAt, minSafetyFactor (+ minSafetyFactorRequired), nodeCount/elementCount/meshSizeMm, quality (minSICN, meanSICN, lowQualityCount), maxStressErrorPercent (high-stress region), trust { meshTrusted, reasons }, hotSpots [{ region, maxVonMisesMPa, nodeId, at, safetyFactor }]; the stress values, safety factor and hot spots exclude the support zone next to fixed-face edges (governingField), whose clamp-singular raw peak is reported as peakAtSupportMPa / peakAtSupportAt / peakAtSupportRegion with supportAdjacentNodeCount and supportZoneRadiusMm; appliedForceN / reactionForceN / equilibriumResidual, meshMs / solveMs.",
-    "type": "object"
-  }
-}

removedOutput schema / required
```
Removed value: -[
-  "ok"
-]
```

Changed1 schema field changedOct 10, 2026

changedInput schema / properties / refine / description

Previous value: -"Automatic mesh refinement until the stress is trusted, inside the element and wall-time budgets (default true). false: one solve at mesh_size."New value: +"One automatic finer pass (0.75x element size) when the stress is untrusted, inside the element budget (default true). false: one solve at mesh_size."

Changed1 schema field changedOct 9, 2026

addedInput schema / properties / refine

Added value: +{
+  "description": "Automatic mesh refinement until the stress is trusted, inside the element and wall-time budgets (default true). false: one solve at mesh_size.",
+  "type": "boolean"
+}

Changed1 schema field changedOct 9, 2026

changedOutput schema / properties / summary / description

Previous value: -"Solved evidence: maxVonMisesMPa, maxVonMisesAt, maxDisplacementMm, maxDisplacementAt, minSafetyFactor (+ minSafetyFactorRequired), nodeCount/elementCount/meshSizeMm, quality (minSICN, meanSICN, lowQualityCount), maxStressErrorPercent, trust { meshTrusted, reasons }, hotSpots [{ region, maxVonMisesMPa, nodeId, at, safetyFactor }], appliedForceN / reactionForceN / equilibriumResidual, meshMs / solveMs."New value: +"Solved evidence: maxVonMisesMPa, maxVonMisesAt, maxDisplacementMm, maxDisplacementAt, minSafetyFactor (+ minSafetyFactorRequired), nodeCount/elementCount/meshSizeMm, quality (minSICN, meanSICN, lowQualityCount), maxStressErrorPercent (high-stress region), trust { meshTrusted, reasons }, hotSpots [{ region, maxVonMisesMPa, nodeId, at, safetyFactor }]; the stress values, safety factor and hot spots exclude the support zone next to fixed-face edges (governingField), whose clamp-singular raw peak is reported as peakAtSupportMPa / peakAtSupportAt / peakAtSupportRegion with supportAdjacentNodeCount and supportZoneRadiusMm; appliedForceN / reactionForceN / equilibriumResidual, meshMs / solveMs."

Changed1 schema field changedSep 28, 2026

changedInput schema / properties / file / description

Previous value: -"Path to a .kcad.ts script declaring at least one feaStudy."New value: +"Path to a .kcad.ts script declaring at least one feaStudy. Hosted server: cannot read files from your machine — pass `code`, or `project:<slug>` for a saved project."

AddedSep 21, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes far beyond the annotations: it discloses that the in-process voxel solver is an estimate with trust.meshTrusted false and is 'never a verified pass', that the safety factor excludes clamp-singular edges (with peakAtSupportMPa reported separately), that refinement re-solves at 0.75x element size, and that specific failure codes (fea.solver.unavailable, fea.safety-factor.below-min) can abort the call. Annotations (readOnlyHint false, openWorld true, idempotent false, destructive false) are consistent with this account of a compute-and-write operation.

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

Conciseness3/5

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

The value proposition is front-loaded, but the body is a dense wall of nested parentheses that partially restates the schema's own parameter descriptions (solver enum, refine default, heatmaps). Sentences earn their place individually, yet the whole is longer than needed for a tool whose schema is fully documented.

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

Completeness5/5

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

For a 14-parameter, multi-solver, file-writing tool, nothing material is missing: input modes, solver fallback, trust semantics, refinement behavior, failure codes and output artifacts are all covered. An output schema exists, so the return-value enumeration is a bonus rather than a gap-filler.

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

Parameters5/5

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

Schema coverage is already 100%, yet the description adds real semantics the schema lacks: FaceQuery matching rules, the warning that a label like 'top' may name multiple faces after a boolean and becomes an error, the distinction between total force in N and scalar-force-plus-direction, the material alias list, and the interaction between mesh_size, refine and the element budget. This is well above the baseline-3 expectation for a fully documented schema.

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?

Opens with a decision-oriented statement of what the tool answers ('whether a part will hold a load') followed by a specific verb+resource ('runs a linear-static structural study') and an enumeration of what it returns (von Mises stress, displacement, safety factor, hot spots, mesh trust flags). An agent can distinguish this from fea_summary or verify without opening the schema.

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

Usage Guidelines4/5

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

Explicitly states the situation that selects this tool and lays out the two supported input modes (study declared in the script vs. inline arguments against a returned shape), plus solver selection guidance ('auto' default, 'calculix' fails up front, 'in-process' is an estimate). It never names a sibling (e.g., fea_summary) as the alternative for post-hoc result retrieval, so it stops short of full when-not routing.

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.