Skip to main content
Glama
brilliant-directories-mcp

brilliant-directories-mcp

Official

updateWidget

Idempotent

Updates an existing widget by ID, leaving omitted fields untouched. Edit content, CSS, JS, or metadata and apply small find-and-replace changes without resending whole code fields.

Instructions

Update a widget - Update an existing widget by widget_id. Fields omitted are untouched. Writes live data. Small edit: replace (no need to read or resend the field).

Cache refresh is automatic. Response includes auto_cache_refreshed: true after successful writes, or auto_cache_refresh: "scheduled" when the refresh is queued to run shortly together with other writes; both are normal and need no refreshSiteCache call. Only if auto_cache_refreshed: false, check auto_cache_refresh_error and retry refreshSiteCache once.

Use when: editing widget HTML (widget_data), CSS (widget_style), JS (widget_javascript), or metadata. Any page or email referencing this widget via [widget=Name] shortcode will render the updated content on next view.

Required: widget_id; for BD's own widget, widget_name + customize: true with whole code fields or replace (makes this site's copy).

Common edits:

  • Content: widget_data, widget_style, widget_javascript

  • Framework: mobile_enabled, ssl_enabled

Renaming via widget_name: DO NOT pass widget_name unless the user explicitly asks to rename the widget. Renaming a widget breaks every [widget=Name] shortcode reference to its old name on every page/email — silently. If the user does ask: same format rules as create ([A-Za-z0-9 -+_]+, runtime-rejected on bad chars); on collision follow the auto-suffix flow (-v2, -v3, ... up to -v10).

See also: createWidget (add new), deleteWidget (remove).

Returns: { status: "success", message: {...updatedRecord}, auto_cache_refreshed?: true|false, auto_cache_refresh?: "scheduled", auto_cache_refresh_error?: "..." }.

For the full field list, see listWidgets.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "updateWidget"
  }
}

Input Schema

NameRequiredDescriptionDefault
replaceNoChange part of a code field: [{field, find, with}]. If find occurs more than once, add nth (1 = first) or all:true. All or nothing; returns an undo.
own_formNotrue: the required being added belongs to this widget's own form, not the homepage hero search
customizeNo
own_iconsNotrue: an icon in the hero search that the search recipe cannot place (a field holding two inputs, such as a price range)
own_videoNotrue: the video change is for this widget's own video, not the homepage hero video
widget_idNo
widget_dataNoHTML. Render strips backslashes here (`\d`→`d`, `\n`→`n`, `\t`→`t`, `\\`→`\`). JS with stripped escapes throws SyntaxError on parse — every handler unbound, widget renders but no clicks/inputs work. Fix: relocate to `widget_javascript`, do not rewrite JS to avoid backslashes. Never relocate existing `<style>`/`<script>` blocks here — only on user-reported breakage. New content: route by type (CSS→`widget_style`, JS→`widget_javascript`). See **Rule: Widget code fields**.
widget_nameNo
widget_styleNoRaw CSS. No `<style>` wrapper — BD wraps at render. Wholly-wrapped value: outer wrapper stripped on storage; concatenated wrappers not stripped. See **Rule: Widget code fields**.
_clear_fieldsNoColumn names to clear to empty string. Available on every `update*` operation. Works on base columns AND EAV/`users_meta` rows (rows preserved with `value=""`). To actually clear a field you MUST use this parameter — sending the field with `""` alone is a no-op (BD drops empty values). To remove a `users_meta` row entirely, use `deleteUserMeta`. See **Rule: Clearing fields**. Example: `_clear_fields: ["h2", "hero_link_url"]`.
widget_javascriptNoJS with `<script>...</script>` wrapper required. BD does not auto-wrap; unwrapped content renders as inert text. No backslash-strip on this field — regex literals (`\d`, `\w`, `\s`) AND string escapes (`\n`, `\t`, `\\`) survive intact. See **Rule: Widget code fields**.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv6.59.691
    • addedInput schema / properties / own_form
      Added value: +{
      +  "description": "true: the required being added belongs to this widget's own form, not the homepage hero search",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / own_icons
      Added value: +{
      +  "description": "true: an icon in the hero search that the search recipe cannot place (a field holding two inputs, such as a price range)",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / own_video
      Added value: +{
      +  "description": "true: the video change is for this widget's own video, not the homepage hero video",
      +  "type": "boolean"
      +}
  2. Changed3 schema fields changedv6.59.638
    • addedInput schema / properties / customize
      Added value: +{
      +  "type": "boolean"
      +}
    • addedInput schema / properties / replace
      Added value: +{
      +  "description": "Change part of a code field: [{field, find, with}]. If find occurs more than once, add nth (1 = first) or all:true. All or nothing; returns an undo.",
      +  "items": {
      +    "properties": {
      +      "all": {
      +        "type": "boolean"
      +      },
      +      "field": {
      +        "enum": [
      +          "widget_data",
      +          "widget_style",
      +          "widget_javascript"
      +        ],
      +        "type": "string"
      +      },
      +      "find": {
      +        "type": "string"
      +      },
      +      "nth": {
      +        "minimum": 1,
      +        "type": "integer"
      +      },
      +      "with": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "field",
      +      "find",
      +      "with"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "widget_id"
      -]
  3. Addedv6.55.39
  4. Removedv6.55.19
  5. Addedv6.49.4
  6. Removedv6.48.1
  7. Addedv6.0.19
  8. Removedv6.0.18
  9. Changed1 schema field changedv6.0.15
    • changedInput schema / properties / widget_data / description
      Previous value: -"Description of the tag group. HTML allowed."New value: +"Main HTML/PHP code body of the widget."
  10. Changed1 schema field changed
    • changedInput schema / properties / widget_data / description
      Previous value: -" Pass raw HTML — do NOT wrap in `<![CDATA[...]]>`, do NOT escape as `&lt;` / `&gt;`, and do NOT include tool-call scaffolding tags (e.g. `<parameter name=\"...\">...</parameter>`, `<invoke>`, `<function_calls>`). BD stores the field value verbatim; any wrapper / escape / scaffolding renders as literal visible text."New value: +"Description of the tag group. HTML allowed."
  11. Addedv6.0.7
  12. Removed
  13. First observedv1.0.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing cache-refresh behavior and the exact response fields to branch on, the silent shortcode breakage from renaming, the collision auto-suffix flow, and the backslash-stripping semantics that differ between widget_data and widget_javascript. Annotations only give the safety profile; the description supplies the operational consequences.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core verb, then well-sectioned with bold headers and a Returns block. It is long, and a couple of lines restate the name ('Update a widget - Update an existing widget'), but nearly every sentence carries actionable content, so size is mostly justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an 11-param mutation tool with no output schema, the description covers prerequisites, rename hazards, cache lifecycle, error/retry path, and return shape. Nothing an agent needs in order to invoke it safely is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 73% schema coverage across 11 params, the description still adds meaning: `replace` as a small-edit path that avoids reading/resending, the 'fields omitted are untouched' rule, the required widget_id vs BD-owned widget path (widget_name + customize), and common-edit groupings. This complements the schema rather than repeating it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Update an existing widget by `widget_id`') and immediately distinguishes scope from createWidget/deleteWidget in the See also section. An agent can tell exactly what the tool does and when to reach for it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when' clause names the fields that apply (HTML/CSS/JS/metadata), names the alternative tools (createWidget, deleteWidget), and adds a strong when-NOT rule ('DO NOT pass `widget_name` unless the user explicitly asks to rename'). Exclusions and alternatives are both present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools