Tools Reference

The server exposes eight tools, split across two authoring surfaces. Each one is deterministic — no model calls happen inside the server.

• JSON form definition — json_validate_form_definition, json_generate_from_schema, json_generate_from_openapi, json_get_widget_spec, get_concept.
• Typed gui.* builder code — dx_list_factories, dx_get_spec, dx_check_code.

The two surfaces have separate validators: use json_validate_form_definition for a JSON definition object, and dx_check_code for gui.* TypeScript — they are not interchangeable.

json_validate_form_definition

Validates a GolemUI form definition against the bundled JSON Schemas. Use it after generating or modifying a definition, to guarantee it is correct before the user pastes it into their codebase.

Input: { formDefinition: { form: [...], states?: {...} } } — pass the JSON object, not a stringified version.

Output: { valid, errors, warnings, expressionWarnings, interpolationWarnings }.

• errors — hard mistakes (typos in a widget type, missing required props, invalid validator shapes). These flip valid to false. Each carries a JSON Pointer path and a concrete fix suggestion (e.g. “format: 'mail' is not valid — did you mean 'email'?”).
• warnings — likely-custom widgets (a type that isn’t a built-in and isn’t close to one). These do not affect valid.
• expressionWarnings — reactive expressions (include.when, disabled.when, …) linted for common mistakes like a missing $form. prefix, a single = in an equality check, or unbalanced brackets.
• interpolationWarnings — string interpolations (${…} in labels and other text) linted for the same class of mistakes. Advisory, like warnings and expressionWarnings; does not affect valid.

json_generate_from_schema

Maps a JSON Schema describing the form-data shape (e.g. an API request body or a Zod-derived schema) into a GolemUI form definition. Handles strings (with format → specialized widgets), numbers, booleans, enums, nested objects, and arrays of objects. The result is validated before it is returned, so it is guaranteed syntactically correct.

Input: { jsonSchema, submitAction?, submitLabel?, layout? } — layout is one of vertical (default), horizontal, or grid.

Output: { formDefinition, unmapped, validation }. Anything the mapper cannot handle is listed in unmapped ({ path, reason }) rather than silently dropped — surface that list to the user.

json_generate_from_openapi

Resolves a specific OpenAPI 3.x operation, dereferences its request-body schema, and emits a validated GolemUI form. Falls back to the operation’s parameters when no JSON request body is present.

Input: { document | documentUrl, operation, submitAction?, submitLabel? } — operation is either "METHOD /path" (e.g. "POST /users") or an exact operationId. Pass the spec as a parsed document or a documentUrl to fetch.

Output: { resolvedOperation, formDefinition, unmapped, validation }, same guarantees as json_generate_from_schema.

See Generating from a schema for full examples of both generators.

json_get_widget_spec

Returns the JSON Schema, kind, a minimal working example, and authoring notes for a single widget. Cheaper than dumping the whole API into the model’s context — reach for it when you need to know which props a widget accepts, what kind value it uses, or what shape its validator takes.

Input: { widgetType } — one of the widget type constants (textinput, dropdown, repeater, flex, …). See the Widgets Reference for the full list.

get_concept

Returns a detailed guide for a cross-cutting concept — things that span multiple widgets and affect the whole form, rather than the API of a single widget. Call it when you need to change a widget’s props based on form state (state-suffixed props like "label.<stateName>": "…") or reuse the same condition across several widgets (include: { in: [...] } / exclude: { from: [...] }).

Input: { concept } — currently supported: "states".

Tip

For a one-off show/hide on a single widget, use include: { when: "…" } or exclude: { when: "…" } directly — no states needed, and no need to call get_concept.

dx_list_factories

The complete gui.* typed-builder reference in a single call: every factory with its namespace, calling convention, a compile-verified example, and its gotchas, plus the cross-cutting patterns (e.g. conditional visibility) and the common authoring rules. The imports and render snippet are tailored to your target framework. Call this first when writing gui.* code and author from it directly — it is self-sufficient for most forms, so you rarely need a follow-up lookup. Import gui only from @golemui/gui-shared; never hand-write raw { kind, type, path } widget JSON.

Input: none.

Output: the full factory catalog — every gui.* factory with its example and gotchas, the shared patterns, and the framework-specific import + render snippet.

dx_get_spec

A deep-dive on a single gui.* factory — its calling convention, a compile-verified example, and authoring notes. You rarely need it: dx_list_factories already carries every factory’s example and the cross-cutting rules. Reach here only to re-confirm one factory in isolation. Distinct from json_get_widget_spec, which returns the JSON form-definition shape for the same widget.

Input: { factory } — the camelCase factory name (textInput, dropdown, radiogroup, button, …).

dx_check_code

Type-checks gui.* builder code (TypeScript) against the real @golemui type declarations — the DX-code counterpart to json_validate_form_definition (which checks a JSON object). The two are not interchangeable. Because GolemUI isn’t in any model’s training data, generated gui.* code is often a confident fabrication that doesn’t compile, and inspection misses it.

Beyond type errors it catches two defects the compiler can’t see: an include/exclude attached as a sibling of a gui.* spread ({ ...gui.inputs.x(...), include } compiles but silently never hides the field — it belongs inside the config argument), and reactive-expression mistakes in when strings (linted by the same engine as json_validate_form_definition).

Input: { code } — the gui.* snippet as a string. A bare array of gui.inputs.* items is fine; the @golemui/gui-shared import is added if missing.

Output: { ok, diagnostics, expressionWarnings }. Each diagnostic carries a TypeScript code (0 for the static lints), a message, line/column, and — for recognized GolemUI mistakes — a fix hint. expressionWarnings are advisory and do not flip ok. Treat ok: false as blocking: apply the fixes and re-check until ok is true.