brilliant-directories-mcp

Official

Overview Schema Source Related Servers Discussions(1)Admin

listWidgets

Read-onlyIdempotent

Retrieve a paginated, read-only list of reusable HTML/CSS/JS widgets to find components for embedding in pages or email templates. Filter and sort results as needed.

Instructions

List widgets - Paginated enumeration of widget records. Read-only.

Lean-by-default keep-list: rows return only widget_id, widget_name, widget_type, short_code, date_updated, revision_timestamp, is_default. The code fields (widget_data, widget_style, widget_javascript) are stripped — restore with include_code=1.

Use when: discovering the reusable HTML/CSS/JS components available for embedding in pages (via [widget=Name] shortcode) or email templates. For fetching one specific widget by ID use getWidget.

Pagination: cursor-based (limit, page). See Rule: Pagination for full cursor/cap/stop semantics.

Filter/sort: property+property_value+property_operator, order_column+order_type. See Rule: Filter operators for the verified-working operator set, silent-drop detection, and derived-field unfilterability.

See also: getWidget (single by ID), createWidget (add new), updateWidget (modify).

Returns: { status: "success", total, current_page, total_pages, next_page, prev_page, message: [...records] }. Each record carries the full widget object (fields enumerated in the table that follows).

Widget object fields (from BD support article 12000108056):

Field	Type	Description
`widget_id`	integer	Primary key (read-only)
`widget_name`	string	Widget name/label - REQUIRED on create; unique per site
`widget_type`	string	Widget classification (default: `Widget`)
`widget_data`	text	Widget HTML content
`widget_style`	text	Widget CSS styles
`widget_javascript`	text	Widget JavaScript code
`widget_settings`	text	Configuration (JSON or serialized)
`widget_values`	text	Widget variable values
`widget_class`	string	CSS class names applied to container
`widget_html_element`	string	Container element (default: `div`)
`div_id`	string	HTML ID attribute for container
`short_code`	string	Shortcode reference for this widget
`ssl_enabled`	integer	`1` if SSL/HTTPS required
`mobile_enabled`	integer	`1` if mobile viewport enabled
`file_type`	string	File type of the widget
`revision_timestamp`	timestamp	Last modified (auto-updated)
`is_default`	boolean	`false` = the site's own record, `true` = an uncustomised master default (read-only; filter with `property=is_default`). See Rule: Default-merge models.

Site records and platform master defaults are merged in the response — see Rule: Default-merge models to filter to one and to sort.

Input Schema

Name	Required	Description
`page`	No	Pagination cursor (use next_page from previous response)
`limit`	No	Records per page (default 25, max 100)
`property`	No	Column key to filter by (present on the response rows; a wrong name silently returns empty). For multi-condition AND, pass parallel arrays here and in `property_value`/`property_operator` — equal length, Nth entries paired. See Rule: Compound filters.
`order_type`	No	Sort direction: ASC or DESC
`include_code`	No	Opt in to return `widget_data`, `widget_style`, `widget_javascript` (the HTML/CSS/JS) on each row. Default stripped. Needed before `updateWidget` edits to the code.
`order_column`	No	Column to sort by — a column key present on the response rows (a wrong name silently returns empty)
`property_value`	No	Value to filter by; array to pair with a `property` array (same length).
`property_operator`	No	Filter operator (word-form; symbol forms WAF-stripped). Single: eq, ne, lt, lte, gt, gte, like, not_like. CSV: in, not_in, between. Substring: contains, starts_with, ends_with (+not_). Date: year_eq, month_eq, day_eq (+not_), since_days, until_days. Length: length_eq, length_lt, length_gt, length_between. Null: is_set, is_not_set, is_null, is_not_null. Array to pair with a `property` array (same length). See Rule: Filter operators for value shapes.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv6.58.3Jul 9, 2026

changedInput schema / properties / property_value / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "items": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "number"
-        }
-      ]
-    },
-    "type": "array"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "boolean"
+  },
+  {
+    "items": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        }
+      ]
+    },
+    "type": "array"
+  }
+]

Changed1 schema field changedv6.58.2Jul 8, 2026

changedInput schema / properties / property_value / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "items": {
-      "type": "string"
-    },
-    "type": "array"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "items": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        }
+      ]
+    },
+    "type": "array"
+  }
+]

Changed11 schema fields changedv6.58.0Jul 5, 2026

addedInput schema / properties / include_code

Added value: +{
+  "default": 0,
+  "description": "Opt in to return `widget_data`, `widget_style`, `widget_javascript` (the HTML/CSS/JS) on each row. Default stripped. Needed before `updateWidget` edits to the code.",
+  "enum": [
+    0,
+    1
+  ],
+  "type": "integer"
+}

changedInput schema / properties / order_column / description

Previous value: -"Column to sort by"New value: +"Column to sort by — a column key present on the response rows (a wrong name silently returns empty)"

addedInput schema / properties / property / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  }
+]

changedInput schema / properties / property / description

Previous value: -"Field name to filter by"New value: +"Column key to filter by (present on the response rows; a wrong name silently returns empty). For multi-condition AND, pass parallel arrays here and in `property_value`/`property_operator` — equal length, Nth entries paired. See Rule: Compound filters."

removedInput schema / properties / property / type
```
Removed value: -"string"
```

addedInput schema / properties / property_operator / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  }
+]

changedInput schema / properties / property_operator / description

Previous value: -"Filter operator (word-form; symbol forms WAF-stripped). Single: eq, ne, lt, lte, gt, gte, like, not_like. CSV: in, not_in, between. Substring: contains, starts_with, ends_with (+not_). Date: year_eq, month_eq, day_eq (+not_), since_days, until_days. Length: length_eq, length_lt, length_gt, length_between. Null: is_set, is_not_set, is_null, is_not_null. See Rule: Filter operators for value shapes."New value: +"Filter operator (word-form; symbol forms WAF-stripped). Single: eq, ne, lt, lte, gt, gte, like, not_like. CSV: in, not_in, between. Substring: contains, starts_with, ends_with (+not_). Date: year_eq, month_eq, day_eq (+not_), since_days, until_days. Length: length_eq, length_lt, length_gt, length_between. Null: is_set, is_not_set, is_null, is_not_null. Array to pair with a `property` array (same length). See Rule: Filter operators for value shapes."

removedInput schema / properties / property_operator / type
```
Removed value: -"string"
```

addedInput schema / properties / property_value / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  }
+]

changedInput schema / properties / property_value / description

Previous value: -"Value to filter by"New value: +"Value to filter by; array to pair with a `property` array (same length)."

removedInput schema / properties / property_value / type
```
Removed value: -"string"
```

Addedv6.55.39May 27, 2026
Removedv6.55.19May 21, 2026
Addedv6.49.4May 18, 2026
Removedv6.48.1May 18, 2026
Addedv6.0.19May 15, 2026
Removedv6.0.18Apr 30, 2026
Addedv6.0.7Apr 20, 2026
RemovedApr 19, 2026
First observedv1.0.0Apr 18, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: it discloses the lean-by-default keep-list (code fields stripped unless include_code=1), cursor pagination semantics, silent-empty behavior on bad property/order_column names, filter-operator caveats, and the default-merge model where site records and platform masters are combined in one response.

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 purpose, safety, and the keep-list before secondary detail, and uses bold headers so an agent can skim. It is longer than strictly necessary — the pagination and filter operators are deferred to external 'Rules' while still consuming space, and the field table is heavy for a list call.

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?

With no output schema, the description carries the full return contract: exact envelope shape (status, total, current_page, total_pages, next_page, prev_page, message) plus a complete field table. Nothing an agent needs to call or interpret this tool is missing.

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

Parameters4/5

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

Schema coverage is already 100%, so the schema carries the load, but the description adds real value beyond it: the field table tells the agent which column keys are legal for `property`/`order_column`, and include_code is framed as a prerequisite for editing code via updateWidget.

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?

Opens with a specific verb+resource ('List widgets'), immediately qualifies scope ('Paginated enumeration of widget records') and safety ('Read-only'), and explicitly separates itself from getWidget, createWidget, and updateWidget by name.

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?

Provides an explicit 'Use when' condition (discovering reusable HTML/CSS/JS components for page/email embedding via shortcode) plus a clear exclusion routing single-record lookups to getWidget. The 'See also' line enumerates every relevant sibling with its role.

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

Deploy Server

listWidgets

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools