kernelcad

Diff Model Geometry

diff_geometry

Read-only

Use this when you need to know WHAT MATERIAL changed between two versions of a model, not just how much. The deeper sibling of diff_scripts: a volume delta alone is ambiguous (a boss that grew and a pocket that deepened report the same magnitude, and a part that only moved reports zero), so this tool answers it with geometry instead of pixels. Baseline is { baseFile } or { baseCode }; the revised side is either another script ({ file } or { code }) or the SAME script re-lowered with { params } overrides — a bag of declared param() name -> new value, which is the one-script form a parameter sweep actually asks for. Bodies pair by name and fall back to declaration-order positional pairing; anything left over is listed in unmatched and raises diff.body.unmatched. Per matched body it returns addedMm3 = volume(revised - base), removedMm3 = volume(base - revised), commonMm3 = volume(base ∩ revised) from OCCT booleans, exact bbox with min/max/extent deltas, face / edge / hole count deltas (hole counts reuse the cylindrical-hole detector), maxDeviationMm (two-sided discrete Hausdorff distance between the two surfaces), and a verdict — identical | moved | resized | topology-changed, precedence topology-changed > resized > moved > identical. Branch on the verdict; cite the numbers. Optional { render: true } also writes an overlay PNG (added green, removed red, unchanged material as a translucent ghost; the scene is a re-runnable .kcad.ts over lossless BREP sidecars) through the render_preview pipeline and fails open (the numeric diff is still returned) when that pipeline is unavailable. Read-only — never touches the active session.

Input Schema

TableJSON Schema

Name	Required	Description
`code`	No	Revised script — inline source. Mutually exclusive with params.
`file`	No	Revised script — path to a .kcad.ts file. Mutually exclusive with params.
`params`	No	Param-override mode: re-lower the BASELINE with these declared param() values changed (e.g. { plateThickness: 8 }). Mutually exclusive with file/code. A name the baseline does not declare fails with the declared-param list in the message.
`render`	No	Also render an overlay PNG — added material green, removed material red — via the render_preview pipeline. Off by default; the numeric table is the agent-facing evidence.
`out_dir`	No	Directory for the overlay PNG, its STL inputs, and the generated overlay script. Default: a temp dir.
`baseCode`	No	Baseline script — inline source.
`baseFile`	No	Baseline script — path to a .kcad.ts file.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes
`base`	No	Baseline summary { featureCount, bodyCount, isAssembly } (success).
`side`	No	Which side failed ('base' \| 'revised') (failure).
`error`	No	Failure message (failure).
`bodies`	No	Per matched body, the material-level delta (success).
`render`	No	Overlay result when render: true — { ok, images, out_dir, script_path, error? }.
`revised`	No	Revision summary { featureCount, bodyCount, isAssembly } (success).
`summary`	No	Verdict counts plus totalAddedMm3 / totalRemovedMm3 / maxDeviationMm.
`errorCode`	No
`unmatched`	No	Bodies present on only one side; each also raises diff.body.unmatched.
`diagnostics`	No

Schema Changelog

Changes observed during successful MCP inspections.

AddedSep 21, 2026

TDQS

A4.9/5.0

Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

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.