pixoo-mcp-server

Overview Schema Source Related Servers Discussions Admin

pixoo_design_brief

pixoo_design_brief

Read-only

Get design rules and device state for a chosen topic to plan Pixoo LED scenes, dashboards, animations, or HTML pages, or to troubleshoot display issues.

Instructions

Return craft guidance and live device context for a design topic. Covers legibility rules, palette discipline, layout zones, animation budget, HTML page authoring, and pre-filled next-tool suggestions based on current device state. The orientation tool to run before authoring a scene, dashboard, animation, or HTML page — or when troubleshooting display issues.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`topic`	Yes	Design topic: text (styled text guidance), scene (composition + layout zones), dashboard (widgets + metrics), animation (motion budget + effects), pixel-art (bitmap + sprite guidance), html (pixoo_render_html pages: loops, clock, sampling), troubleshooting (device + display issues).

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`topic`	No	The topic that was requested.
`htmlRenderer`	No	Whether pixoo_render_html can render: available; disabled (PIXOO_HTML_ENABLED=false, so the tool is not listed); or no_browser (no browser found, so the tool fails browser_unavailable until one is installed).
`craftGuidance`	No	Markdown-formatted craft rules: legibility floors, palette discipline, layout zones, and technique guidance specific to the topic.
`deviceContext`	No	Live device state snapshot at the time of the request.
`iconCategories`	No	Built-in icon names grouped by category (weather, arrows, status, media). Use names in pixoo_compose_scene icon elements.
`availableThemes`	No	Available named scene themes (e.g. "midnight", "ember"). Use in background.theme or pixoo_display_text theme param.
`nextToolSuggestions`	No	Suggested next steps based on topic and device state.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.4.0Sep 30, 2026

changedInput schema / properties / topic / description

Previous value: -"Design topic: text (styled text guidance), scene (composition + layout zones), dashboard (widgets + metrics), animation (motion budget + effects), pixel-art (bitmap + sprite guidance), troubleshooting (device + display issues)."New value: +"Design topic: text (styled text guidance), scene (composition + layout zones), dashboard (widgets + metrics), animation (motion budget + effects), pixel-art (bitmap + sprite guidance), html (pixoo_render_html pages: loops, clock, sampling), troubleshooting (device + display issues)."

changedInput schema / properties / topic / enum

Previous value: -[
-  "text",
-  "scene",
-  "dashboard",
-  "animation",
-  "pixel-art",
-  "troubleshooting"
-]New value: +[
+  "text",
+  "scene",
+  "dashboard",
+  "animation",
+  "pixel-art",
+  "html",
+  "troubleshooting"
+]

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "topic",
-      "craftGuidance",
-      "deviceContext",
-      "nextToolSuggestions",
-      "availableThemes",
-      "iconCategories"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "topic",
+      "craftGuidance",
+      "deviceContext",
+      "htmlRenderer",
+      "nextToolSuggestions",
+      "availableThemes",
+      "iconCategories"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / htmlRenderer

Added value: +{
+  "description": "Whether pixoo_render_html can render: available; disabled (PIXOO_HTML_ENABLED=false, so the tool is not listed); or no_browser (no browser found, so the tool fails browser_unavailable until one is installed).",
+  "enum": [
+    "available",
+    "disabled",
+    "no_browser"
+  ],
+  "type": "string"
+}

Changed8 schema fields changedv1.2.0Sep 25, 2026

changedOutput schema / properties / nextToolSuggestions / items / description

Previous value: -"A suggested next-step tool with rationale and optional pre-filled args."New value: +"A recommended follow-up call with its arguments pre-filled."

addedOutput schema / properties / nextToolSuggestions / items / properties / args

Added value: +{
+  "additionalProperties": {},
+  "description": "Pre-filled arguments for the call; {} when the tool needs none.",
+  "properties": {},
+  "type": "object"
+}

removedOutput schema / properties / nextToolSuggestions / items / properties / rationale

Removed value: -{
-  "description": "Why this tool is relevant given current state.",
-  "type": "string"
-}

addedOutput schema / properties / nextToolSuggestions / items / properties / reason

Added value: +{
+  "description": "Why this step is recommended given the current device state.",
+  "type": "string"
+}

removedOutput schema / properties / nextToolSuggestions / items / properties / suggestedArgs

Removed value: -{
-  "additionalProperties": {},
-  "description": "Pre-filled argument suggestions as a key-value object.",
-  "properties": {},
-  "type": "object"
-}

removedOutput schema / properties / nextToolSuggestions / items / properties / tool

Removed value: -{
-  "description": "Tool name to try next.",
-  "type": "string"
-}

addedOutput schema / properties / nextToolSuggestions / items / properties / toolName
```
Added value: +{
+  "description": "Tool to call next.",
+  "type": "string"
+}
```

changedOutput schema / properties / nextToolSuggestions / items / required

Previous value: -[
-  "tool",
-  "rationale"
-]New value: +[
+  "toolName",
+  "reason",
+  "args"
+]

Changed6 schema fields changedv1.1.1Aug 24, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "topic",
+      "craftGuidance",
+      "deviceContext",
+      "nextToolSuggestions",
+      "availableThemes",
+      "iconCategories"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode.",
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "topic",
-  "craftGuidance",
-  "deviceContext",
-  "nextToolSuggestions",
-  "availableThemes",
-  "iconCategories"
-]

First observedv1.0.0Jun 17, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it returns live device state and pre-filled next-tool suggestions that vary with current device condition, making clear the output is dynamic rather than static documentation. It does not cover auth requirements or whether device discovery must precede it.

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

Conciseness5/5

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

Three tight sentences: capability first, coverage second, usage routing third. Every clause earns its place with no redundancy, and the most actionable routing advice is placed last as a clear call to action.

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?

An output schema exists, so return values need no explanation here. Combined with a fully documented enum parameter and readOnlyHint annotations, the description supplies everything an agent needs to decide when to call it and what topic values map to which authoring task.

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

Parameters3/5

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

Schema description coverage is 100% and the single enum parameter is fully documented with per-value explanations in the schema. The description only restates the coverage areas (legibility, palette, layout zones, animation budget, HTML authoring) without adding format or interpretation guidance beyond the schema, so baseline 3 is correct.

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 ('return craft guidance and live device context') and scopes it to a design topic. It also positions itself against siblings by declaring that it is the orientation tool to run before authoring scenes, dashboards, animations, or HTML pages, so an agent can distinguish it from pixoo_compose_scene and pixoo_render_html without opening their schemas.

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

Usage Guidelines4/5

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

Gives clear usage context: run it before authoring a scene, dashboard, animation, or HTML page, or when troubleshooting display issues. This effectively routes the agent ahead of the sibling authoring tools. It lacks an explicit when-not condition or a named alternative for cases where it shouldn't be called, so it falls short of a 5.

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

Deploy Server