Skip to main content
Glama

HALO Homebridge AI Surfaces

by com.homebridgepc.agent-commerce
OverviewDiscussionsAdmin

Display live Homebridge product media

display_homebridge_product_media
Read-onlyIdempotent

Optional compatibility widget for clients supporting MCP Apps. Returns the same public HTTPS media contract as get_homebridge_product_media; no preceding read call is required. Use only for an explicit gallery request when a widget is useful. Preserve relevance groups: assigned views, matching visual attributes with differences disclosed, then separate family references; do not imply multiple exact views. Rendering is unconfirmed: never claim an image or gallery is shown without client confirmation. Ordinary URL and galleryUrl fallbacks remain available. Creates no commerce state.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
skuNo
limitNo
categoryYes
mediaTypesNo
productHandleYes

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
mediaYes
productYes
boundariesYes
galleryUrlYes
mediaCountYes
generatedAtYes
schemaVersionYes
dataProvenanceYes
selectedVariantYes
requestedMediaTypesYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / media / items / properties / relevance
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "differingAttributes": {
+      "additionalProperties": {
+        "additionalProperties": false,
+        "properties": {
+          "selected": {
+            "type": "string"
+          },
+          "shown": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "selected",
+          "shown"
+        ],
+        "type": "object"
+      },
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "evidenceSource": {
+      "enum": [
+        "shopify_variant_association",
+        "shopify_variant_options",
+        "product_membership"
+      ],
+      "type": "string"
+    },
+    "group": {
+      "enum": [
+        "selected_variant",
+        "matching_visual_attributes",
+        "product_family"
+      ],
+      "type": "string"
+    },
+    "matchedAttributes": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "reviewedDuplicateGroup": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "group",
+    "evidenceSource",
+    "matchedAttributes",
+    "differingAttributes"
+  ],
+  "type": "object"
+}
  2. Changed12 schema fields changed
    • addedOutput schema / properties / galleryUrl
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / media / items / properties / associatedVariantIds
      Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / media / items / properties / association
      Added value: +{
+  "enum": [
+    "shopify_variant_featured_image",
+    "shopify_product_media"
+  ],
+  "type": "string"
+}
    • addedOutput schema / properties / media / items / properties / exactVariantDepictionVerified
      Added value: +{
+  "const": false,
+  "type": "boolean"
+}
    • addedOutput schema / properties / media / items / properties / fidelityNote
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / media / items / properties / height
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • addedOutput schema / properties / media / items / properties / mimeType
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • addedOutput schema / properties / media / items / properties / relationship
      Added value: +{
+  "enum": [
+    "representative",
+    "product_family"
+  ],
+  "type": "string"
+}
    • addedOutput schema / properties / media / items / properties / url
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • addedOutput schema / properties / media / items / properties / width
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • changedOutput schema / properties / media / items / required
      Previous value: -[
-  "mediaId",
-  "type",
-  "position",
-  "altText",
-  "previewImage",
-  "sources",
-  "embeddedUrl"
-]New value: +[
+  "url",
+  "mimeType",
+  "width",
+  "height",
+  "relationship",
+  "association",
+  "associatedVariantIds",
+  "exactVariantDepictionVerified",
+  "fidelityNote",
+  "mediaId",
+  "type",
+  "position",
+  "altText",
+  "previewImage",
+  "sources",
+  "embeddedUrl"
+]
    • changedOutput schema / required
      Previous value: -[
-  "schemaVersion",
-  "generatedAt",
-  "product",
-  "selectedVariant",
-  "requestedMediaTypes",
-  "media",
-  "mediaCount",
-  "dataProvenance",
-  "boundaries"
-]New value: +[
+  "galleryUrl",
+  "schemaVersion",
+  "generatedAt",
+  "product",
+  "selectedVariant",
+  "requestedMediaTypes",
+  "media",
+  "mediaCount",
+  "dataProvenance",
+  "boundaries"
+]
  3. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the readOnly and idempotent annotations, the description discloses that rendering is unconfirmed and forbids claiming an image or gallery is shown without client confirmation. It also defines relevance-group ordering, notes URL and galleryUrl fallbacks, and states it creates no commerce state, all of which are valuable behavioral details.

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?

The purpose is front-loaded and every sentence carries information. The relevance-group sentence is dense and could be clearer, but the overall length is justified by the compatibility, ordering, and rendering caveats.

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?

With an output schema and annotations present, the description covers the tool's purpose, sibling relationship, use scope, rendering caveat, and side-effect-free behavior. It is mostly complete, but the complete absence of parameter semantics prevents a perfect score.

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

Parameters2/5

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

Schema description coverage is 0% and the description never explains sku, limit, category, productHandle, or mediaTypes. The schema provides names and enums, but the low coverage means the description should compensate; it does not, leaving domain-specific meaning such as productHandle versus sku or the intended category values to inference.

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 deliverable, returning the same public HTTPS media contract as get_homebridge_product_media, and immediately differentiates this widget by noting no preceding read call is required. The title and name align with a display action, so an agent can determine what the tool does.

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 tool is explicitly scoped to an explicit gallery request when a widget is useful, and positioned for clients supporting MCP Apps. It references get_homebridge_product_media as the contract-equivalent alternative and clarifies that this variant does not require a prior read call, providing clear routing guidance.

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

All HALO Homebridge AI Surfaces 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