> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.athenaintel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.athenaintel.com/_mcp/server.

# UI Registry (Assistant.js)

> Create interactive tools and dynamic instructions for AI-powered User Interface assets using the registry from Assistant.js

The `registry` object from `./Assistant.js` provides methods for creating interactive tools and dynamic instructions that the AI assistant can use to interact with your HTML interface in User Interface assets.

### Basic Tool Registration

Use `registry.addTool()` to create tools that the AI assistant can invoke to interact with your UI:

```javascript
import { registry } from "./Assistant.js"

registry.addTool({
  toolName: "toolName",
  description: "Description of what the tool does",
  parameters: {
    type: "object",
    properties: {
      paramName: {
        type: "string",
        description: "Parameter description"
      }
    },
    required: ["paramName"]
  },
  execute: async (args) => {
    // Tool implementation
    return { success: true, result: "Tool executed" }
  }
})
```

### Tool Configuration Options

Each tool requires the following configuration:

* **toolName** (string, required): Unique identifier for the tool
* **description** (string, required): Clear description of the tool's purpose and functionality
* **parameters** (object, required): JSON Schema defining the tool's input parameters
  * Use `type: "object"` with `properties` to define parameter structure
  * Include `required` array for mandatory parameters
  * Use appropriate types: `"string"`, `"number"`, `"boolean"`, `"array"`, `"object"`
  * Add `enum` arrays for restricted value sets
* **execute** (function, required): Async function that implements the tool logic
  * Receives the parameters as the first argument
  * Should return an object with results or error information
  * Can interact with DOM elements, make API calls, or perform other operations

### Dynamic Instructions with addInstruction

In addition to tools, the `registry` supports adding dynamically updatable instructions to the model context using `addInstruction`. Use this to stream concise, structured state into the assistant's system prompt.

```javascript
import { registry } from "./Assistant.js";

// Create an instruction with an initial value; JSON strings are recommended
const bmiInstruction = registry.addInstruction("{}");

function computeBMI(height, weight) {
  if (!Number.isFinite(height) || !Number.isFinite(weight) || height <= 0 || weight <= 0) return NaN;
  return weight / (height * height);
}

function updateBMI({ height, weight }) {
  const bmi = computeBMI(height, weight);
  const payload = {
    height,
    weight,
    bmi: Number.isFinite(bmi) ? Number(bmi.toFixed(4)) : null
  };
  bmiInstruction.update(JSON.stringify(payload));
}

// Later, when no longer needed:
// bmiInstruction.remove();
```

### Best Practices for Instructions

* Prefer compact JSON strings so the model can easily parse state
* Update only when underlying state changes to avoid noise
* Use one instruction per cohesive state domain (e.g., BMI widget state)
* Keep tool descriptions short; let instructions carry dynamic state that tools manipulate

### Example: Form Field Updater Tool

```javascript
registry.addTool({
  toolName: "updateTicketField",
  description: "Update a field in the ticket creation form.",
  parameters: {
    type: "object",
    properties: {
      field: {
        type: "string",
        description: "Field to update",
        enum: ["priority", "sender", "email", "category", "subject", "body"]
      },
      value: {
        type: "string",
        description: "Value to set"
      }
    },
    required: ["field", "value"]
  },
  execute: async ({ field, value }) => {
    const elem = document.getElementById(field)
    if (elem) {
      elem.value = value
      return { success: true }
    } else {
      return { success: false, error: "Field not found" }
    }
  }
})
```

### Example: Form Submission Tool

```javascript
registry.addTool({
  toolName: "submitTicket",
  description: "Submit the ticket creation form and return all form values.",
  parameters: {
    type: "object",
    properties: {},
    additionalProperties: false
  },
  execute: async () => {
    const fields = ["priority", "sender", "email", "category", "subject", "body"]
    const data = {}
    fields.forEach(f => {
      const elem = document.getElementById(f)
      data[f] = elem ? elem.value : null
    })

    // Show success message
    document.getElementById("resultMsg").style.display = ""
    setTimeout(() => {
      document.getElementById("resultMsg").style.display = "none"
    }, 2400)

    return { success: true, data }
  }
})
```

### Tool Design Best Practices

1. **Clear Tool Names**: Use descriptive, action-oriented names (e.g., `"updateField"`, `"submitForm"`, `"toggleVisibility"`)
2. **Comprehensive Descriptions**: Explain what the tool does and when to use it
3. **Proper Parameter Validation**: Use JSON Schema to define clear parameter requirements
4. **Error Handling**: Return meaningful error messages when operations fail
5. **Consistent Return Format**: Always return objects with success/error indicators
6. **DOM Safety**: Check for element existence before manipulation
7. **User Feedback**: Provide visual feedback for user actions when appropriate

### Return Format Guidelines

Tools should return objects that indicate success or failure:

* **Success**: `{ success: true, result: data }` or `{ success: true, data: formData }`
* **Error**: `{ success: false, error: "Error message" }`
* Include relevant data in the response that the AI assistant can use

### Form-Based Interface Guidelines

When creating form-based interfaces:

* Use semantic HTML with proper `id` attributes for form elements
* Create tools for both individual field updates and form submission
* Provide validation and user feedback mechanisms
* Consider accessibility and user experience in tool design