> ## Documentation Index
> Fetch the complete documentation index at: https://docs.widgentic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> The seven tools of a widgentic MCP server — name, description as the model sees it, and the JSON Schema of each input — derived from the tool definitions.

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.

```json theme={null}
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

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

```json theme={null}
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

## list\_themes

List the themes registered on this server — name, label, description and token map for each. Pass any listed name as render\_widget's 'theme' input instead of composing tokens by hand.

```json theme={null}
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

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

```json theme={null}
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

## 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).

```json theme={null}
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

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

```json theme={null}
{
  "type": "object",
  "properties": {
    "widget": {
      "type": "string",
      "description": "Widget kind id, as returned by list_widgets."
    },
    "data": {
      "type": [
        "array",
        "object",
        "string",
        "number",
        "boolean",
        "null"
      ],
      "description": "Widget data matching the kind's documented dataShape."
    },
    "hints": {
      "type": "object",
      "description": "Optional renderer hints (see the kind's hints doc)."
    },
    "meta": {
      "type": "object",
      "description": "Optional metadata (title, subtitle, source, ...)."
    },
    "format": {
      "type": "string",
      "enum": [
        "both",
        "html",
        "widget",
        "page",
        "app"
      ],
      "description": "Output selection (default 'both'): 'html' fragment only (no payload block — plain consumers only; strands widgentic-aware hosts), 'widget' payload block only, 'page' a self-contained styled HTML document (plus the payload block), 'app' the page as a ui:// text/html resource for inline display — Apps hosts use the html resource, native hosts the payload block."
    },
    "theme": {
      "type": [
        "object",
        "string"
      ],
      "description": "Either a registered theme NAME (discover with list_themes — the simplest path, e.g. 'dark') or a token map of bare token names to CSS string values, always strings ('6px', not 6). When the user refers to a theme by name ('use nord dark'), pass the NAME — their saved themes live server-side and are the source of truth; do NOT reconstruct the tokens from memory (your copy drifts the moment they edit it). Inline maps are for one-off, unsaved styling. Discover tokens, defaults, and presets with list_theme_tokens; author extras as 'x-<name>' custom variables. Applied to 'page' output and embedded in the widget payload for native hosts on every format."
    }
  },
  "required": [
    "widget",
    "data"
  ],
  "additionalProperties": false
}
```

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

```json theme={null}
{
  "type": "object",
  "properties": {
    "widget": {
      "type": "string",
      "description": "The rendered widget's kind."
    },
    "action": {
      "type": "string",
      "description": "Binding identifier: the element's dotted template path, or \"load\"."
    },
    "args": {
      "type": "object",
      "description": "Arguments as resolved in the element's descriptor.",
      "additionalProperties": true
    },
    "payload": {
      "type": "object",
      "description": "The widget's current payload { kind, data, hints?, meta? }.",
      "additionalProperties": true
    },
    "at": {
      "type": "string",
      "description": "Inside a group: dotted path of the item payload within 'payload' (e.g. data.items.2)."
    },
    "item": {
      "type": "string",
      "description": "Inside a group: the item's kind."
    }
  },
  "required": [
    "widget",
    "action",
    "payload"
  ],
  "additionalProperties": false
}
```