Skip to main content
Descriptions are the exact text advertised to agents over tools/list; they carry the steering, so they are longer than a reference usually is.

​
list_widgets

List the available widget kinds with their purpose, expected data shape, an example data value, and supported hints. Call this first to decide which widget fits your data, then call render_widget. ALWAYS call it again when the user asks what widgets are available or says they saved/imported something in the designer — catalogs are served per API key and change between calls; never answer from an earlier listing.

​
list_schemas

List the user’s saved shared data schemas — name, label, description, and the schema object itself. Call this when the user asks for a widget built on one of their schemas (‘use my person schema’): bind the schema’s actual properties and set the widget’s descriptor.dataSchemaRef to the schema’s NAME instead of copying the schema inline — an inline copy forks the moment the user edits the shared one. Served per API key, like list_widgets; anonymous keys see an empty list.

​
list_actions

List the user’s saved shared actions — name, label, description, kind, and for http actions the method and the input/output schemas. Call this when the user wants a widget to DO something (‘add a refresh button using my weather action’): bind a listed action by name with “action”: { “ref”: “<name>” }, mapping an http action’s input from the widget’s data (a prompt action takes no input mapping — its binds list the data paths its text needs). The listing is the action’s contract, not its transport — the URL, headers and query stay on the server. If nothing listed fits, DESCRIBE the action the user should create in the designer; never draft an inline definition with a URL or credentials you cannot know. Served per API key, like list_widgets; anonymous keys see an empty list.

​
list_themes

List the themes registered on this server — name, label, description, token map and shared styles for each — and ‘defaults’, the theme the user chose for light and for dark hosts. Leave render_widget’s ‘theme’ out to use those defaults; pass a listed name only when the user asks for a different theme. A theme’s ‘styles’ define .wg- classes (a .wg-btn, say) that widgets rendered under it can use in their templates.

​
list_theme_tokens

List the theming vocabulary for render_widget’s ‘theme’ input: every token name with its light-mode default, ready-made presets (e.g. dark), and the value rules. Call this before building a theme.

​
get_authoring_guide

Get the complete guide for AUTHORING widget and theme JSON: entry shapes, the template DSL’s node forms and safety rules, identifier rules and reserved kinds, style and schema constraints, theme tokens, and per-user limits. Call this before drafting a custom widget or theme for your user — you draft the JSON, your user imports and saves it in the designer at widgentic.dev (there is no registration tool).

​
render_widget

Validate and render a widget. Returns the rendered HTML plus an embedded widgentic payload block that widgentic-aware hosts can mount natively. On invalid input, returns a structured error describing what to correct. To show several widgets at once, render ONE ‘group’ (items of mixed kinds, layout hints) instead of calling repeatedly. Write ‘widget’ first and any ‘hints’ before ‘data’ in the arguments: hosts that stream the call can then show the widget, with its labels, columns and image places, while its data arrives.

​
execute_action

Called by widgentic widgets, not by agents: runs a widget’s bound http action (a stored, author-declared request) server-side and returns the re-rendered widget. Requires a key with the ‘execute’ scope. Agents should call render_widget instead.

​
preview_widget

Called by the widgentic app template while a render’s input is still streaming, not by agents: renders the partial payload of a stored widget so the frame can show it as it arrives. Agents should call render_widget instead.