Server Quality Checklist

Tool Scores

• pixoo_push_imageA
  4/5.0
  Behavior4/5

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

  Annotations already cover idempotency (indy), open-world behavior, and not destructive. The description adds valuable behavioral detail: it returns the exact downsampled result as an image content block, and it makes explicit the resize/display pipeline. It doesn' t contradict the annotations. Slight gaps such as failure modes, but for a non-destuctive image utility this is solid.

  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?

  The description is three compact sentences with no filler. It front-loads the main pipeline, then covers optional push behavior, return value, and kernel guidance. Every sentence earns its place.

  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 only 4 parameters, 1 required, and no output schema explain, the description is sufficient: covers input source, resizing modes, kernel choice, push default, and return-value semantics. The agent can select parameters from either schema or description, and know exactly what to expect back from the tool.

  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 description coverage is 100%, so the schema already defines fit, kernel, push, and source. The description adds real selection guidance on which kernel to choose (nearest for pixel art, lanczos3/mitchell for photos), which is above the baseline and helps the agent pick semantic effective values. Small extra value beyond schema, hence a 4.

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

  Purpose4/5

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

  The description states the operation clearly: load an image from a local path or HTTPS URL, resize it to fit the LED grid, optionally push to the display, and return the downsampled result. This is a specific verb-plus-resource description. It is functionally distinct from the text/device sibling tools, though it does not explicitly name them or contrast itself with a tool like pixoo_compose_scene.

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

  Usage Guidelines3/5

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

  The description outlines the pipeline and the 'optionally push' behavior, which implies a preview-only use case when push=false. It does not explicitly state when to use this tool over siblings such as pixoo_compose_scene, pixoo_overlay_text, or pixoo_control_device. There is enough context for the agent to infer, but no direct that when-to-use guidance.

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

• pixoo_design_briefA
  4.1/5.0
  Behavior3/5

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

  The readOnlyHint annotation already tells agents this is a safe read-only operation, and the description adds useful context about what it returns: craft guidance, live device context, and next-tool suggestions. It does not disclose details about device unavailability or failure modes, but the annotation lowers the burden on the description.

  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?

  The description is two sentences, front-loads the core purpose, and wastes no words. It covers scope, coverage areas, and a clear temporal use case without over-explaining.

  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?

  For a single-parameter tool with a full enum description, an output schema, and a readOnly annotation, the description is sufficiently complete. It tells agents what the tool does, what topics it covers, when to run it, and how it relates to downstream authoring tools.

  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?

  The input schema fully documents the only parameter, 'topic,' including an enum and per-value descriptions. The description's mention of topics like legibility rules, palette discipline, layout zones, and animation budget reinforces the enum but does not add essential meaning beyond the schema already covers.

  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?

  The description uses a specific verb-resource pair ('Return craft guidance and live device context for a design topic') and clearly defines the tool's role as an orientation tool rather than an authoring tool. It distinguishes itself from sibling tools by framing it as the step to run before authoring or troubleshooting.

  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?

  The description explicitly states when to use the tool: before authoring a scene, dashboard, or animation, and when troubleshooting display issues. It does not explicitly name alternative tools or exclusion criteria, but the guidance is clear enough to route an agent correctly.

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

• pixoo_compose_sceneA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare idempotentHint=true and destructiveHint=false, covering the safety profile. The description adds genuine behavioral detail beyond that: it returns "the rendered scene as an image content block for immediate inspection" and discloses the z-order rule "Elements render back-to-front in array order." It does not mention the default push-to-device side effect, but this is not a contradiction and the safety info is already well covered by the annotations.

  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?

  The description is three sentences of pure information: the core action with capability summary, the return behavior, and the explicit routing with a requirement. Every sentence earns its place and the most important decision-relevant facts are front-loaded.

  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?

  For a tool with a rich nested schema, output schema, and annotations, the description does its job: it establishes the composition model, states the z-order semantics, and gives an explicit decision path to sibling tools. The main minor gap is that it does not flag that the scene is, by default, pushed to the device via the 'push' parameter, but that behavior is already fully documented in the schema itself.

  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?

  The input schema covers 100% of parameters with meaningful descriptions, including the element oneOf discrimination, so the baseline is 3. The description's element type list is a useful summary but it simply reflects what the schema's oneOf already documents. It does not add meaning beyond the schema, which the rubric says the baseline already accounts for.

  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?

  The description starts with the specific verb-resource action "Compose a full scene" and enumerates the element families it covers (text, icons, widgets, shapes, bitmaps, images, sprites) plus the animation capabilities (effects, keyframes, static or animated). It also names the sibling tool pixoo_display_text to make the distinction explicit, so an agent can tell this tool apart without opening the schema.

  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?

  The description gives explicit routing guidance: "For text-only display use pixoo_display_text" and "run pixoo_design_brief with topic 'scene' or 'dashboard' for layout and palette guidance." This clearly handles the most confusable sibling and the companion design tool, but does not mention exclusions for the other siblings (e.g., pixoo_push_image, among others), so the guidance is strong but not exhaustive.

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

• pixoo_discover_devicesA
  4.4/5.0
  Behavior4/5

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

  Annotations already establish readOnly and openWorld hints. The description adds value by disclosing the network dependency (requires internet) and the specific external endpoint (app.divoom-gz.com), which are important behavioral traits not captured by annotations. Does not contradict annotations.

  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 concise sentences, front-loaded with the primary purpose, then the setup context and routing to an alternative. Every sentence earns its place; no filler or redundancy.

  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?

  Moderate-low complexity tool with an output schema, so return values need not be described. The description covers purpose, network prerequisites, and post-condition (set PIXOO_IP). Slightly more could be said about what discovery returns, but the output schema already handles that.

  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 coverage is 100% with clear description, default, minimum, and maximum for timeoutMs. The narrative description adds nothing about the parameter, but with full schema coverage the baseline of 3 is appropriate since no extra meaning is needed.

  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?

  The description uses a specific verb and resource ('Find Pixoo devices on the local network') and identifies the method via Divoom's cloud discovery endpoint. It distinguishes itself from all sibling tools, which are for display, control, or composition, by being the discovery step.

  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?

  States explicitly when to use this tool ('Run once during initial setup'), what to do with the result (set PIXOO_IP in server configuration), and names the alternative for ongoing control (pixoo_control_device). This gives an agent complete routing guidance.

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

• pixoo_control_deviceA
  4.5/5.0
  Behavior4/5

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

  Annotations already mark the call idempotent and non-destructive, so the description's main job is to disclose the threshold value of calling it with no params vs applying changes before reading back state. It also usefully notes that pixoo_discover_devices may be needed first. It does not provide deeper details like persistence or authentication, but none are essential here.

  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 sentences, no filler, operationally efficient. The first sentence defines the tool's scope, the second explains the two calling patterns, and the third handles the environment prerequisite.

  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?

  For an optional padded 4-param device-control tool with fully described input fields and an existing output schema, the description covers the main workflow and prerequisite. An agent has enough to invoke it correctly: choose only params if changing state, else omit them to read state.

  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?

  The schema already documents every parameter at 100% coverage, so a baseline of 3 applies. The description adds helpful usage semantics by making the interaction rule explicit: 'no params = read', 'any params = apply then read back'. That is valuable beyond the schema structure.

  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?

  Description states a specific operation ('Read or change device state') and enumerates the exact dimensions affected: brightness, screen on/off, channel, and clock face. This clearly separates it from the sibling content-related tools like pixoo_display_text and pixoo_push_image.

  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?

  It explicitly explains when to call with no params (read only) versus with params (apply changes), and names pixoo_discover_devices as a prerequisite when PIXOO_IP is unknown. It could slightly strengthen by naming which siblings are NOT appropriate for device-state changes, but the guidance is otherwise clear.

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

• pixoo_display_textA
  4.5/5.0
  Behavior4/5

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

  The description goes beyond the annotations (idempotentHint true, destructiveHint false) by exposing the push-to-device side effect and the fact that the tool returns the rendered frame as an image content block for inspection. This is valuable behavioral information about what physically happens to the display and what the agent should expect in the output.

  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?

  The description is concise, front-loaded with the primary purpose, and every sentence earns its place. It covers the core action, the output behavior, the sibling distinction, and a design brief next step all without significantly bloating.

  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?

  Combined with the thorough input schema, output schema, and annotations, the description is complete enough for an agent to decide when to call this tool, what parameters to consider, what to expect from the return, and what to do for richer scenes. The shape does not have an obvious missing aspect.

  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?

  The input schema is fully documented at 100% coverage with detailed descriptions for font, text, align, style, theme, effect, position, background, brightness, and push. The tool description adds no substantive param-level semantics beyond the schema already provides. It names a few style aspects, but the schema itself explains those concepts in detail.

  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?

  The description states a specific verb ('Render'), a specific resource ('text onto the Pixoo display'), and a push-and-return behavior, ending with an image content block. It also fully differentiates itself from the available sibling ('ptixoo_compose_sceene') by declaring itself as the primary text-on-console display tool. This gives the agent enough high-level directional information before inspecting the schema.

  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?

  The description explicitly says this is the primary tool for text-only display and directs the agent to 'pixoo_compose_cene' for layers, icons, widgets, or animations. It also recommends running 'pixoo_design_brief' with topic 'text' first. That is a useful when-to-use vs. when-not-to-use instruction sequence.

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

• pixoo_overlay_textA
  4.7/5.0
  Behavior5/5

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

  Annotations already cover idempotency and non-destructiveness, so the description correctly adds behavioral context beyond them: overlays persist across channel switches, rendering happens on-device, and the feature is not previewable. This is genuinely useful invocation-relevant detail.

  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?

  The description is brief, front-loaded with the core action, and every sentence contributes: action, mode usage, persistence detail, limitation, and sibling routing. No filler or tautology.

  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 11 parameters, 2 required, and a rich input schema, the description captures the behavioral context an agent needs: mode semantics, overlay slots, persistence, and when to choose this tool versus pixoo_display_text. No meaningful selection or invocation context is missing.

  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%, so the baseline is 3; the description reinforces slot/font semantics and mode behavior, but every parameter already has a descriptive schema helper. It does not need to repeat the full parameter list.

  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?

  Description uses specific verbs ('Set or clear') and a specific resource ('device-native scrolling text overlay'), immediately distinguishing its function. It also names the sibling it is not — pixoo_display_text — so an agent can tell them apart without opening schemas.

  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?

  Describes exactly when to invoke 'set' versus 'clear', and explicitly recommends pixoo_display_text for styled, previewable text. This gives clear routing guidance for the main alternative.

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