kernelCAD

Add Text

add_text

Idempotent

Use this when you need to author text into a kernelCAD script before the last top-level return. One authoring path, selected by mode:

'sketch' — insert a sketch.text(...) call. The emitted sketch is chainable: pair with subsequent .extrude(...) / cut(...) edits to land an engraved or raised text feature.
'emboss' — insert a <shape>.embossText({...}) chained call onto an existing Shape target. Use for engraved brand text on faces (Ray-Ban temple, CE mark, model number). depth > 0 raises text out of the face; depth < 0 engraves text into the face. Lowers via replicad drawText → sketchOnFace → extrude → fuse|cut. Default font is the runtime-bundled Liberation Sans. Side-effect-free; returns the modified code plus diagnostics from re-evaluating. Each mode fails closed on its own missing required params.

Input Schema

Name	Required	Description
`code`	Yes	The .kcad.ts source code.
`face`	No	mode:'emboss' — target face — canonical name ('top'/'bottom'/'left'/'right'/'front'/'back') or label.
`font`	No	mode:'sketch' — optional logical font name or .ttf file path; defaults to bundled Liberation Sans.
`mode`	Yes	Which text-authoring path to use.
`size`	No	mode:'sketch'\|'emboss' — glyph cap height in mm (positive finite).
`align`	No	mode:'sketch' — horizontal alignment relative to position (default left); mode:'emboss' — relative to the UV anchor (default center).
`depth`	No	mode:'emboss' — signed extrusion depth in mm: positive emboss out, negative engrave in. Must be non-zero.
`bindAs`	No	mode:'sketch' — emits `const <bindAs> = sketch.text(...)`; mode:'emboss' — emits `const <bindAs> = <target>.embossText(...);`.
`target`	No	mode:'emboss' — variable name of the Shape to chain onto (inserted verbatim).
`anchorU`	No	mode:'emboss' — U anchor in [0, 1] face-local (0=umin, 0.5=centre, 1=umax). Default 0.5.
`anchorV`	No	mode:'emboss' — V anchor in [0, 1] face-local. Default 0.5.
`content`	No	mode:'sketch' — text content (UTF-8, non-empty, non-whitespace).
`position`	No	mode:'sketch' — [x, y] anchor in mm. Default [0, 0].
`rotation`	No	mode:'sketch' — CCW rotation in degrees around position (default 0); mode:'emboss' — CCW rotation in the face tangent plane (default 0).
`scaleMode`	No	mode:'emboss' — Drawing.sketchOnFace scaling mode. Default original.
`fontFamily`	No	mode:'emboss' — optional logical font name or .ttf file path; defaults to bundled Liberation Sans.
`textContent`	No	mode:'emboss' — text content (UTF-8, non-empty, non-whitespace).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 11, 2026

removedOutput schema / properties

Removed value: -{
-  "binding_name": {
-    "description": "JS const name bound to the new construct (when one was created).",
-    "type": "string"
-  },
-  "diagnostics": {
-    "description": "Diagnostics from re-evaluating the modified source.",
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "error": {
-    "description": "Failure message (present when ok is false).",
-    "type": "string"
-  },
-  "new_code": {
-    "description": "Modified .kcad.ts source (present on success). Caller persists it.",
-    "type": "string"
-  },
-  "ok": {
-    "description": "Whether the edit applied and re-evaluated cleanly.",
-    "type": "boolean"
-  }
-}

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

Changed1 schema field changedJun 15, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "binding_name": {
+      "description": "JS const name bound to the new construct (when one was created).",
+      "type": "string"
+    },
+    "diagnostics": {
+      "description": "Diagnostics from re-evaluating the modified source.",
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "error": {
+      "description": "Failure message (present when ok is false).",
+      "type": "string"
+    },
+    "new_code": {
+      "description": "Modified .kcad.ts source (present on success). Caller persists it.",
+      "type": "string"
+    },
+    "ok": {
+      "description": "Whether the edit applied and re-evaluated cleanly.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}

AddedJun 13, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare the mutation/idempotency/safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds real value beyond that: it discloses the drawText→sketchOnFace→extrude→fuse|cut pipeline, that it returns modified code plus diagnostics, and that each mode fails closed on missing params.

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?

It is front-loaded with the when-to-use trigger and then a clean per-mode breakdown. The detail is dense but each clause earns its place; slightly long for the payload, keeping it from a 5.

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 17-parameter tool the description covers the critical complexity: mode selection, mode-specific behavior, defaults, failure behavior, and pipeline. With 100% schema coverage and an output schema present, return-value details need not be repeated, and the description 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?

With 100% schema coverage the baseline is 3, but the description adds genuinely useful mode-conditional semantics — clarifying which parameters belong to 'sketch' vs 'emboss' and the meaning of depth sign. This helps an agent select correct parameters beyond the per-param schema text.

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 states a specific verb+resource ('author text into a kernelCAD script') and immediately disambiguates the two authoring paths ('sketch' vs 'emboss') with concrete examples (Ray-Ban temple, CE mark). An agent can tell exactly what this tool produces and how it differs from other add_* tools.

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?

It gives clear triggering context ('Use this when you need to author text... before the last top-level return') and explains which mode to pick for which scenario (chainable sketched text vs. engraved/embossed text on an existing face). It stops short of naming specific sibling tools to avoid, which is the only gap.

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.