Skip to main content
Glama
Sign In

Brix Digital Signage

by com.brixsignage
OverviewDiscussionsAdmin

List items of one kind

list_items
Read-onlyIdempotent

List items of one kind with their ids, so other tools can act on them.

When to use:

  • A request names a screen, file, playlist or location and you need its id.

  • Seeing what runs now (casts, emergencies), what is wrong now (alerts), approval requests, deleted items (recycle_bin), or who is in the workspace and what they may do (people, roles).

When NOT to use:

  • Reading one item's contents: use get_items.

  • History over time: use get_fleet_report.

What to know:

  • Rows are short (id, name, nodeId, counts), never configs or members; only locations this connection can see. people rows add each person's role at each location (never sign-in details); roles rows add their permissions.

  • A kind this connection cannot read is an error, not an empty list. people and roles are read-only here (invite with create_items); changing a person's access, roles, API keys and billing stays with a signed-in person in the Brix console, so a connected app can never widen access. To see what this connection itself may do, use get_items kind account.

  • media, alerts and recycle_bin come newest first. Every call counts toward the connection's 30 tool calls a minute, so page with offset instead of re-listing.

Parameters:

  • kind: the list to read; app_types and connectors are what create_items can make. A connectors row's setup is here (create_items makes it) or console (a person connects it in the Brix console, and it is then used by its id).

  • Filters (all optional, combined with AND, ignored on kinds they do not name): q (name contains, any kind but people and roles); status (screens online/offline/pairing; approvals pending by default, approved, rejected, withdrawn); nodeId (screens at that location and below; alerts at that location only); tag (screens, media); mediaKind and folderId (media); severity and screenId (alerts); binKind (recycle_bin).

  • limit: page size for media and approvals (default 50); other kinds give 100 a page. offset: pass nextOffset while hasMore.

  • Example: {kind:"screens", status:"offline", nodeId:"on_west"}.

Input Schema

NameRequiredDescriptionDefault
qNoName contains.
tagNoTag.
kindYesWhich list.
limitNoPage size.
nodeIdNoLocation id.
offsetNoRows to skip.
statusNoScreen or approval state.
binKindNoRecycle bin kind.
folderIdNoMedia folder id.
screenIdNoScreen id.
severityNoAlert severity.
mediaKindNoMedia type.

Output Schema

NameRequiredDescriptionDefault
kindNoThe kind listed.
itemsNoOne short row per item: id, name, location (nodeId) and counts. Never full configs or members.
totalNoHow many items match, across all pages.
hasMoreNotrue when another page exists; call again with offset = nextOffset.
nextOffsetNoThe offset of the next page (present when hasMore).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / kind / enum
      Previous value: -[
-  "screens",
-  "media",
-  "playlists",
-  "schedules",
-  "layouts",
-  "creatives",
-  "apps",
-  "data_sources",
-  "screen_groups",
-  "locations",
-  "media_folders",
-  "emergency_templates",
-  "casts",
-  "emergencies",
-  "alerts",
-  "approvals",
-  "recycle_bin",
-  "app_types",
-  "connectors"
-]New value: +[
+  "screens",
+  "media",
+  "playlists",
+  "schedules",
+  "layouts",
+  "creatives",
+  "apps",
+  "data_sources",
+  "screen_groups",
+  "locations",
+  "media_folders",
+  "emergency_templates",
+  "casts",
+  "emergencies",
+  "alerts",
+  "approvals",
+  "recycle_bin",
+  "app_types",
+  "connectors",
+  "people",
+  "roles"
+]
  2. Changed1 schema field changed
    • changedOutput schema / properties / items / description
      Previous value: -"One short row per item: id, name, location (nodeId) and counts. Never full configs, members or billing."New value: +"One short row per item: id, name, location (nodeId) and counts. Never full configs or members."
  3. Changed12 schema fields changed
    • changedInput schema / properties / binKind / description
      Previous value: -"recycle_bin only: screen, media, playlist, schedule, layout, creative, app, data-source or media-folder."New value: +"Recycle bin kind."
    • changedInput schema / properties / folderId / description
      Previous value: -"media only: one folder's files (ids from kind media_folders)."New value: +"Media folder id."
    • changedInput schema / properties / kind / description
      Previous value: -"The kind to list. See the description for what each kind holds."New value: +"Which list."
    • changedInput schema / properties / limit / description
      Previous value: -"media and approvals only: page size, 1-200 (default 50)."New value: +"Page size."
    • changedInput schema / properties / mediaKind / description
      Previous value: -"media only: image, video, audio, pdf, web, rss or app."New value: +"Media type."
    • changedInput schema / properties / nodeId / description
      Previous value: -"screens: this location and every location under it. alerts: this location only. Location ids come from kind locations."New value: +"Location id."
    • changedInput schema / properties / offset / description
      Previous value: -"Skip this many matches; pass nextOffset from the previous page."New value: +"Rows to skip."
    • changedInput schema / properties / q / description
      Previous value: -"Case-insensitive part of the name, e.g. \"lobby\" finds \"Lobby left\"."New value: +"Name contains."
    • changedInput schema / properties / screenId / description
      Previous value: -"alerts only: one screen's alerts."New value: +"Screen id."
    • changedInput schema / properties / severity / description
      Previous value: -"alerts only."New value: +"Alert severity."
    • changedInput schema / properties / status / description
      Previous value: -"screens: online, offline or pairing. approvals: pending (default), approved, rejected or withdrawn."New value: +"Screen or approval state."
    • changedInput schema / properties / tag / description
      Previous value: -"screens and media: only items with this exact tag (case-insensitive)."New value: +"Tag."
  4. Changed14 schema fields changed
    • addedInput schema / properties / binKind
      Added value: +{
+  "description": "recycle_bin only: screen, media, playlist, schedule, layout, creative, app, data-source or media-folder.",
+  "type": "string"
+}
    • addedInput schema / properties / folderId
      Added value: +{
+  "description": "media only: one folder's files (ids from kind media_folders).",
+  "type": "string"
+}
    • changedInput schema / properties / kind / description
      Previous value: -"Which kind of item to list; see the tool description."New value: +"The kind to list. See the description for what each kind holds."
    • changedInput schema / properties / kind / enum
      Previous value: -[
-  "playlists",
-  "schedules",
-  "layouts",
-  "apps",
-  "data_sources",
-  "screen_groups",
-  "locations",
-  "media_folders",
-  "active_casts"
-]New value: +[
+  "screens",
+  "media",
+  "playlists",
+  "schedules",
+  "layouts",
+  "creatives",
+  "apps",
+  "data_sources",
+  "screen_groups",
+  "locations",
+  "media_folders",
+  "emergency_templates",
+  "casts",
+  "emergencies",
+  "alerts",
+  "approvals",
+  "recycle_bin",
+  "app_types",
+  "connectors"
+]
    • addedInput schema / properties / limit
      Added value: +{
+  "description": "media and approvals only: page size, 1-200 (default 50).",
+  "maximum": 200,
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / mediaKind
      Added value: +{
+  "description": "media only: image, video, audio, pdf, web, rss or app.",
+  "type": "string"
+}
    • addedInput schema / properties / nodeId
      Added value: +{
+  "description": "screens: this location and every location under it. alerts: this location only. Location ids come from kind locations.",
+  "type": "string"
+}
    • changedInput schema / properties / offset / description
      Previous value: -"Skip this many matching items (default 0)."New value: +"Skip this many matches; pass nextOffset from the previous page."
    • changedInput schema / properties / q / description
      Previous value: -"Only items whose name contains this text (case-insensitive)."New value: +"Case-insensitive part of the name, e.g. \"lobby\" finds \"Lobby left\"."
    • addedInput schema / properties / screenId
      Added value: +{
+  "description": "alerts only: one screen's alerts.",
+  "type": "string"
+}
    • addedInput schema / properties / severity
      Added value: +{
+  "description": "alerts only.",
+  "enum": [
+    "info",
+    "warning",
+    "critical"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / status
      Added value: +{
+  "description": "screens: online, offline or pairing. approvals: pending (default), approved, rejected or withdrawn.",
+  "enum": [
+    "online",
+    "offline",
+    "pairing",
+    "pending",
+    "approved",
+    "rejected",
+    "withdrawn"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / tag
      Added value: +{
+  "description": "screens and media: only items with this exact tag (case-insensitive).",
+  "type": "string"
+}
    • addedOutput schema / properties
      Added value: +{
+  "hasMore": {
+    "description": "true when another page exists; call again with offset = nextOffset.",
+    "type": [
+      "boolean",
+      "null"
+    ]
+  },
+  "items": {
+    "description": "One short row per item: id, name, location (nodeId) and counts. Never full configs, members or billing.",
+    "items": {
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "kind": {
+    "description": "The kind listed.",
+    "type": [
+      "string",
+      "null"
+    ]
+  },
+  "nextOffset": {
+    "description": "The offset of the next page (present when hasMore).",
+    "type": [
+      "integer",
+      "null"
+    ]
+  },
+  "total": {
+    "description": "How many items match, across all pages.",
+    "type": [
+      "integer",
+      "null"
+    ]
+  }
+}
  5. Changed1 schema field changed
    • addedInput schema / properties / kind / description
      Added value: +"Which kind of item to list; see the tool description."
  6. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value on top: short row shape, visibility limited to locations this connection can see, an unreadable kind raises an error rather than returning [], people/roles are read-only with privilege escalation blocked in the console, and newest-first ordering for media/alerts/recycle_bin. The 30-calls-per-minute rate limit and the advice to page with offset instead of re-listing are exactly the kind of operational context annotations cannot express.

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 one-line purpose, then scannable labelled sections, so an agent can jump to the relevant block. It is long and some sentences are heavily nested with parentheticals (the connectors row setup line), but almost no text is redundant given 12 parameters and 21 kinds.

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

Completeness4/5

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

Return format is covered by the output schema, so the description does not need to restate it, and everything an agent needs to call correctly is present. One gap: it instructs using "get_items kind account" while "account" is not in the kind enum, which would make that follow-up call fail as written.

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?

Schema coverage is 100%, so baseline would be 3, but the description goes well beyond it: it maps each filter to the kinds it applies to (status for screens/approvals, nodeId for screens and alerts with different depth semantics, tag for screens/media, binKind for recycle_bin), states filters combine with AND and are ignored on kinds they do not name, and gives page-size defaults (50 for media/approvals, 100 otherwise) plus offset/nextOffset paging. The worked example anchors the filter combination.

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 and resource ("List items of one kind with their ids") and states the downstream reason ("so other tools can act on them"), which immediately distinguishes it from get_items and get_fleet_report. The kind enumeration and the note that rows are id+name+counts make the boundary even sharper.

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 "When to use" / "When NOT to use" sections name the alternative tools and the conditions that select them (get_items for one item's contents, get_fleet_report for history). It also gives positive triggers such as needing an id for a named screen, playlist or location.

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

All Brix Digital Signage toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources