Skip to content
{gui.}

Tools Reference

The server exposes five tools. Each one is deterministic — no model calls happen inside the server.

validate_form_definition

Section titled “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 }.

  • 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.

generate_from_json_schema

Section titled “generate_from_json_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.

generate_from_openapi

Section titled “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 generate_from_json_schema.

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

get_widget_spec

Section titled “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

Section titled “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".