kernelCAD

Query Geometry

query

Read-onlyIdempotent

Use this when you need to resolve or inspect topology against a script's lowered geometry. Pass the script as code (inline; works on a hosted server) or file. Selected by mode (default 'evaluate'):

'evaluate' — list the faces a Query matches ({ query }). Pass expect:'unique' to assert exactly-one.
'resolve' — resolve one ref to one face ({ ref }).
'lineage' — the creating/modifying history of a face ({ ref }; feature_id defaults to the last feature). Query forms (faces only; edge/vertex kinds return query.unsupported-entity-type):
a bare face label: 'top', 'bottom', 'left', 'right', 'front', 'back', or a hole/cutout slot like 'wall'.
@kc[/face/] — feature ids are the ones refs print, e.g. '@kc[box_1/face/top]', '@kc[hole_1/face/wall]'.
@kcq[face(, ...)] — filters AND together: createdBy("box_1"), withLabel("top"), geometryType(PLANE|CYLINDER|CONE|SPHERE|TORUS|BSPLINE_SURFACE), closestTo([x,y,z]) or closestTo([x,y,z], k), containsPoint([x,y,z]); combine with union(a, b), intersection(a, b), subtraction(a, b). Example: '@kcq[face(geometryType(CYLINDER), closestTo([0,0,10]))]'. Each matched face comes back with its canonical @kc ref, centroid, normal and area.

Input Schema

Name	Required	Description
`ref`	No	mode:'resolve'\|'lineage' — one face: '@kc[box_1/face/top]', '@kcq[...]', or '<feature-id>.<label>' (lineage).
`code`	No	Inline kernelCAD script source.
`file`	No	Path to a .kcad.ts script file. Hosted server: cannot read files from your machine — pass `code`, or `project:<slug>` for a saved project.
`mode`	No	Resolution mode (default 'evaluate').
`query`	No	mode:'evaluate' — Query: a bare face label ('top'), an @kc[<feature-id>/face/<label>] ref, an @kcq[face(...)] expression, or { ast }.
`expect`	No	mode:'evaluate' — 'unique' asserts exactly-one.
`feature_id`	No	Optional FeatureId; defaults to the last lowered shape (use "auto" for lineage).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 19, 2026
- addedInput schema / properties / query / type
```
Added value: +[
+  "string",
+  "object"
+]
```

Changed2 schema fields changedOct 16, 2026

changedInput schema / properties / query / description

Previous value: -"mode:'evaluate' — Query input: @kc[...] / @kcq[...] string or { ast } object."New value: +"mode:'evaluate' — Query: a bare face label ('top'), an @kc[<feature-id>/face/<label>] ref, an @kcq[face(...)] expression, or { ast }."

changedInput schema / properties / ref / description

Previous value: -"mode:'resolve'|'lineage' — topology ref string."New value: +"mode:'resolve'|'lineage' — one face: '@kc[box_1/face/top]', '@kcq[...]', or '<feature-id>.<label>' (lineage)."

Changed2 schema fields changedOct 11, 2026

removedOutput schema / properties

Removed value: -{
-  "candidates": {
-    "description": "mode:'resolve' — near-miss candidates (failure).",
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "chain": {
-    "description": "mode:'lineage' — HistoryMap walk.",
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "entities": {
-    "description": "mode:'evaluate' — matched entities.",
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "entity": {
-    "additionalProperties": true,
-    "description": "mode:'resolve' — the single matched entity.",
-    "type": "object"
-  },
-  "error": {
-    "type": "string"
-  },
-  "errorCode": {
-    "type": "string"
-  },
-  "ok": {
-    "type": "boolean"
-  },
-  "query": {
-    "additionalProperties": true,
-    "description": "mode:'evaluate' — the resolved Query ({ ast }).",
-    "type": "object"
-  },
-  "ref": {
-    "description": "mode:'resolve' — the resolved ref string.",
-    "type": "string"
-  },
-  "warnings": {
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  }
-}

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

Changed1 schema field changedSep 28, 2026

changedInput schema / properties / file / description

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

Changed1 schema field changedJun 15, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "candidates": {
+      "description": "mode:'resolve' — near-miss candidates (failure).",
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "chain": {
+      "description": "mode:'lineage' — HistoryMap walk.",
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "entities": {
+      "description": "mode:'evaluate' — matched entities.",
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "entity": {
+      "additionalProperties": true,
+      "description": "mode:'resolve' — the single matched entity.",
+      "type": "object"
+    },
+    "error": {
+      "type": "string"
+    },
+    "errorCode": {
+      "type": "string"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "query": {
+      "additionalProperties": true,
+      "description": "mode:'evaluate' — the resolved Query ({ ast }).",
+      "type": "object"
+    },
+    "ref": {
+      "description": "mode:'resolve' — the resolved ref string.",
+      "type": "string"
+    },
+    "warnings": {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}

AddedJun 13, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses error semantics ('edge/vertex kinds return query.unsupported-entity-type'), the assertion behavior of expect:'unique', the hosted-server file-read limitation, and the feature_id defaulting rule. This is exactly the behavioral context annotations cannot carry.

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?

Front-loads the usage trigger, then uses scannable bullets for the three modes and a second list for query grammar, ending with the return shape. Dense and every section is load-bearing despite the length.

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 7-parameter, three-mode tool, the description covers mode selection, query grammar, assertion behavior, defaults, error cases, and the hosted-server constraint. With an output schema present, it correctly omits return-value documentation and is complete for correct invocation.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3, but the description goes further by explaining mode defaults, the accepted query forms (bare label, @kc ref, @kcq expression, ast), and the lineage feature_id default. It adds genuine semantic depth over the schema rather than restating it.

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

Purpose4/5

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

Opens with a specific verb pair and resource: 'resolve or inspect topology against a script's lowered geometry.' An agent immediately knows this is a geometry/topology query tool rather than a script runner or mesh tool. It doesn't explicitly name which sibling to prefer (ray_pick, get_selection, inspect), so it stops short of the top score.

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 lead sentence gives a clear trigger condition ('when you need to resolve or inspect topology'), and the per-mode bullets explain what each mode is for, which is strong within-tool routing. There are no explicit when-not-to-use statements or named alternatives among the many siblings, so it falls 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.

All kernelCAD tools Inspect

Try in Browser

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.