HALO Homebridge AI Surfaces

Configure a Homebridge architectural fire pit

configure_homebridge_fire_pit

Idempotent

Resolve an exact Homebridge fire-pit configuration against the live Shopify catalog ONLY after the buyer has stated and confirmed body style, tabletop finish, fuel source, and shape. NEVER infer a missing selection. Call this tool exactly once for the completed selection. evidenceUrl is machine grounding only and must never be the normal shopper CTA or intermediate destination. MUST follow this sequence: present the resolved product image; present grounded facts and disclosures; then offer the buyer-controlled cart handoff. Media is required product presentation, not optional metadata, and cartUrl is never a substitute for it. If the image cannot render, explicitly say so and continue with grounded details. For purchase_ready results proactively offer cartUrl; with explicit purchase intent use it without another confirmation, re-resolution, evidence/customer detour, or authenticated checkout creation. customerUrl is only for optional inspection. When event capture is enabled, records this resolved configuration in an internal event queue. It cannot place an order or collect payment.

Input Schema

TableJSON Schema

Name	Required	Description
`shape`	Yes	The shape explicitly chosen by the buyer; never infer it.
`fuelType`	Yes	The fuel source explicitly chosen by the buyer; never default to Propane or Natural Gas.
`bodyStyle`	Yes	The body style explicitly chosen by the buyer; never infer it.
`tabletopFinish`	Yes	The tabletop finish explicitly chosen by the buyer; never infer it.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`sku`	Yes
`media`	Yes
`price`	Yes
`product`	Yes
`variantId`	Yes
`boundaries`	Yes
`availability`	Yes
`primaryMedia`	Yes
`commerceLinks`	Yes
`configuration`	Yes
`productHandle`	Yes
`purchaseState`	Yes
`shopperAction`	Yes
`actionBindings`	Yes
`shopperActions`	Yes
`technicalFacts`	Yes
`referenceAction`	Yes
`inspectionAction`	Yes
`checkoutEligibility`	Yes
`requiredDisclosures`	Yes
`shopperHandoffPolicy`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 8, 2026

changedOutput schema / properties / media / properties / primary / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "altText": {
-        "type": "string"
-      },
-      "associatedVariantIds": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "association": {
-        "enum": [
-          "shopify_variant_featured_image",
-          "shopify_product_media"
-        ],
-        "type": "string"
-      },
-      "embeddedUrl": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "exactVariantDepictionVerified": {
-        "const": false,
-        "type": "boolean"
-      },
-      "fidelityNote": {
-        "type": "string"
-      },
-      "height": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "mediaId": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "mimeType": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "position": {
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "previewImage": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "height": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "url": {
-                "type": "string"
-              },
-              "width": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "required": [
-              "url",
-              "width",
-              "height"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "relationship": {
-        "enum": [
-          "representative",
-          "product_family"
-        ],
-        "type": "string"
-      },
-      "sources": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "format": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "height": {
-              "anyOf": [
-                {
-                  "type": "number"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "mimeType": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "url": {
-              "type": "string"
-            },
-            "width": {
-              "anyOf": [
-                {
-                  "type": "number"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            }
-          },
-          "required": [
-            "url",
-            "mimeType",
-            "format",
-            "width",
-            "height"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "type": {
-        "enum": [
-          "image",
-          "video",
-          "external_video",
-          "model_3d"
-        ],
-        "type": "string"
-      },
-      "url": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "width": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "required": [
-      "url",
-      "mimeType",
-      "width",
-      "height",
-      "relationship",
-      "association",
-      "associatedVariantIds",
-      "exactVariantDepictionVerified",
-      "fidelityNote",
-      "mediaId",
-      "type",
-      "position",
-      "altText",
-      "previewImage",
-      "sources",
-      "embeddedUrl"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "altText": {
+        "type": "string"
+      },
+      "associatedVariantIds": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "association": {
+        "enum": [
+          "shopify_variant_featured_image",
+          "shopify_product_media"
+        ],
+        "type": "string"
+      },
+      "embeddedUrl": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "exactVariantDepictionVerified": {
+        "const": false,
+        "type": "boolean"
+      },
+      "fidelityNote": {
+        "type": "string"
+      },
+      "height": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "mediaId": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "mimeType": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "position": {
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "previewImage": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "height": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "url": {
+                "type": "string"
+              },
+              "width": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "required": [
+              "url",
+              "width",
+              "height"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "relationship": {
+        "enum": [
+          "representative",
+          "product_family"
+        ],
+        "type": "string"
+      },
+      "relevance": {
+        "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"
+      },
+      "sources": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "format": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "height": {
+              "anyOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "mimeType": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "url": {
+              "type": "string"
+            },
+            "width": {
+              "anyOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "required": [
+            "url",
+            "mimeType",
+            "format",
+            "width",
+            "height"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "type": {
+        "enum": [
+          "image",
+          "video",
+          "external_video",
+          "model_3d"
+        ],
+        "type": "string"
+      },
+      "url": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "width": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "url",
+      "mimeType",
+      "width",
+      "height",
+      "relationship",
+      "association",
+      "associatedVariantIds",
+      "exactVariantDepictionVerified",
+      "fidelityNote",
+      "mediaId",
+      "type",
+      "position",
+      "altText",
+      "previewImage",
+      "sources",
+      "embeddedUrl"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / primaryMedia / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "altText": {
-        "type": "string"
-      },
-      "associatedVariantIds": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "association": {
-        "enum": [
-          "shopify_variant_featured_image",
-          "shopify_product_media"
-        ],
-        "type": "string"
-      },
-      "embeddedUrl": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "exactVariantDepictionVerified": {
-        "const": false,
-        "type": "boolean"
-      },
-      "fidelityNote": {
-        "type": "string"
-      },
-      "height": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "mediaId": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "mimeType": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "position": {
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "previewImage": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "height": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "url": {
-                "type": "string"
-              },
-              "width": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "required": [
-              "url",
-              "width",
-              "height"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "relationship": {
-        "enum": [
-          "representative",
-          "product_family"
-        ],
-        "type": "string"
-      },
-      "sources": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "format": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "height": {
-              "anyOf": [
-                {
-                  "type": "number"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "mimeType": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "url": {
-              "type": "string"
-            },
-            "width": {
-              "anyOf": [
-                {
-                  "type": "number"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            }
-          },
-          "required": [
-            "url",
-            "mimeType",
-            "format",
-            "width",
-            "height"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "type": {
-        "enum": [
-          "image",
-          "video",
-          "external_video",
-          "model_3d"
-        ],
-        "type": "string"
-      },
-      "url": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "width": {
-        "anyOf": [
-          {
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "required": [
-      "url",
-      "mimeType",
-      "width",
-      "height",
-      "relationship",
-      "association",
-      "associatedVariantIds",
-      "exactVariantDepictionVerified",
-      "fidelityNote",
-      "mediaId",
-      "type",
-      "position",
-      "altText",
-      "previewImage",
-      "sources",
-      "embeddedUrl"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "altText": {
+        "type": "string"
+      },
+      "associatedVariantIds": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "association": {
+        "enum": [
+          "shopify_variant_featured_image",
+          "shopify_product_media"
+        ],
+        "type": "string"
+      },
+      "embeddedUrl": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "exactVariantDepictionVerified": {
+        "const": false,
+        "type": "boolean"
+      },
+      "fidelityNote": {
+        "type": "string"
+      },
+      "height": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "mediaId": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "mimeType": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "position": {
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "previewImage": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "height": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "url": {
+                "type": "string"
+              },
+              "width": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "required": [
+              "url",
+              "width",
+              "height"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "relationship": {
+        "enum": [
+          "representative",
+          "product_family"
+        ],
+        "type": "string"
+      },
+      "relevance": {
+        "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"
+      },
+      "sources": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "format": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "height": {
+              "anyOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "mimeType": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "url": {
+              "type": "string"
+            },
+            "width": {
+              "anyOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "required": [
+            "url",
+            "mimeType",
+            "format",
+            "width",
+            "height"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "type": {
+        "enum": [
+          "image",
+          "video",
+          "external_video",
+          "model_3d"
+        ],
+        "type": "string"
+      },
+      "url": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "width": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "url",
+      "mimeType",
+      "width",
+      "height",
+      "relationship",
+      "association",
+      "associatedVariantIds",
+      "exactVariantDepictionVerified",
+      "fidelityNote",
+      "mediaId",
+      "type",
+      "position",
+      "altText",
+      "previewImage",
+      "sources",
+      "embeddedUrl"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed2 schema fields changedSep 7, 2026

changedOutput schema / properties / media / properties / primary / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "altText": {
-        "type": "string"
-      },
-      "embeddedUrl": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "mediaId": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "position": {
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "previewImage": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "height": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "url": {
-                "type": "string"
-              },
-              "width": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "required": [
-              "url",
-              "width",
-              "height"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "sources": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "format": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "height": {
-              "anyOf": [
-                {
-                  "type": "number"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "mimeType": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "url": {
-              "type": "string"
-            },
-            "width": {
-              "anyOf": [
-                {
-                  "type": "number"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            }
-          },
-          "required": [
-            "url",
-            "mimeType",
-            "format",
-            "width",
-            "height"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "type": {
-        "enum": [
-          "image",
-          "video",
-          "external_video",
-          "model_3d"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "mediaId",
-      "type",
-      "position",
-      "altText",
-      "previewImage",
-      "sources",
-      "embeddedUrl"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "altText": {
+        "type": "string"
+      },
+      "associatedVariantIds": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "association": {
+        "enum": [
+          "shopify_variant_featured_image",
+          "shopify_product_media"
+        ],
+        "type": "string"
+      },
+      "embeddedUrl": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "exactVariantDepictionVerified": {
+        "const": false,
+        "type": "boolean"
+      },
+      "fidelityNote": {
+        "type": "string"
+      },
+      "height": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "mediaId": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "mimeType": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "position": {
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "previewImage": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "height": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "url": {
+                "type": "string"
+              },
+              "width": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "required": [
+              "url",
+              "width",
+              "height"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "relationship": {
+        "enum": [
+          "representative",
+          "product_family"
+        ],
+        "type": "string"
+      },
+      "sources": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "format": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "height": {
+              "anyOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "mimeType": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "url": {
+              "type": "string"
+            },
+            "width": {
+              "anyOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "required": [
+            "url",
+            "mimeType",
+            "format",
+            "width",
+            "height"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "type": {
+        "enum": [
+          "image",
+          "video",
+          "external_video",
+          "model_3d"
+        ],
+        "type": "string"
+      },
+      "url": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "width": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "url",
+      "mimeType",
+      "width",
+      "height",
+      "relationship",
+      "association",
+      "associatedVariantIds",
+      "exactVariantDepictionVerified",
+      "fidelityNote",
+      "mediaId",
+      "type",
+      "position",
+      "altText",
+      "previewImage",
+      "sources",
+      "embeddedUrl"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / primaryMedia / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "altText": {
-        "type": "string"
-      },
-      "embeddedUrl": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "mediaId": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "position": {
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "previewImage": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "height": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "url": {
-                "type": "string"
-              },
-              "width": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "required": [
-              "url",
-              "width",
-              "height"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "sources": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "format": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "height": {
-              "anyOf": [
-                {
-                  "type": "number"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "mimeType": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "url": {
-              "type": "string"
-            },
-            "width": {
-              "anyOf": [
-                {
-                  "type": "number"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            }
-          },
-          "required": [
-            "url",
-            "mimeType",
-            "format",
-            "width",
-            "height"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "type": {
-        "enum": [
-          "image",
-          "video",
-          "external_video",
-          "model_3d"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "mediaId",
-      "type",
-      "position",
-      "altText",
-      "previewImage",
-      "sources",
-      "embeddedUrl"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "altText": {
+        "type": "string"
+      },
+      "associatedVariantIds": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "association": {
+        "enum": [
+          "shopify_variant_featured_image",
+          "shopify_product_media"
+        ],
+        "type": "string"
+      },
+      "embeddedUrl": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "exactVariantDepictionVerified": {
+        "const": false,
+        "type": "boolean"
+      },
+      "fidelityNote": {
+        "type": "string"
+      },
+      "height": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "mediaId": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "mimeType": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "position": {
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "previewImage": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "height": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "url": {
+                "type": "string"
+              },
+              "width": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "required": [
+              "url",
+              "width",
+              "height"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "relationship": {
+        "enum": [
+          "representative",
+          "product_family"
+        ],
+        "type": "string"
+      },
+      "sources": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "format": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "height": {
+              "anyOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "mimeType": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "url": {
+              "type": "string"
+            },
+            "width": {
+              "anyOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "required": [
+            "url",
+            "mimeType",
+            "format",
+            "width",
+            "height"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "type": {
+        "enum": [
+          "image",
+          "video",
+          "external_video",
+          "model_3d"
+        ],
+        "type": "string"
+      },
+      "url": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "width": {
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "url",
+      "mimeType",
+      "width",
+      "height",
+      "relationship",
+      "association",
+      "associatedVariantIds",
+      "exactVariantDepictionVerified",
+      "fidelityNote",
+      "mediaId",
+      "type",
+      "position",
+      "altText",
+      "previewImage",
+      "sources",
+      "embeddedUrl"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed5 schema fields changedSep 5, 2026

addedOutput schema / properties / actionBindings

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "explicitPurchaseIntent": {
+      "const": "shopperAction",
+      "type": "string"
+    },
+    "inspectEvidence": {
+      "const": "referenceAction",
+      "type": "string"
+    },
+    "inspectExactProduct": {
+      "const": "inspectionAction",
+      "type": "string"
+    }
+  },
+  "required": [
+    "inspectExactProduct",
+    "explicitPurchaseIntent",
+    "inspectEvidence"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / inspectionAction

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "available": {
+      "type": "boolean"
+    },
+    "buyerControlled": {
+      "type": "boolean"
+    },
+    "collectsPayment": {
+      "const": false,
+      "type": "boolean"
+    },
+    "label": {
+      "type": "string"
+    },
+    "method": {
+      "anyOf": [
+        {
+          "const": "GET",
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "placesOrder": {
+      "const": false,
+      "type": "boolean"
+    },
+    "shopperFacing": {
+      "type": "boolean"
+    },
+    "type": {
+      "enum": [
+        "view_exact_product",
+        "open_cart",
+        "request_consultation",
+        "inspect_evidence"
+      ],
+      "type": "string"
+    },
+    "url": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "type",
+    "label",
+    "url",
+    "method",
+    "available",
+    "shopperFacing",
+    "buyerControlled",
+    "placesOrder",
+    "collectsPayment"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / referenceAction

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "available": {
+          "type": "boolean"
+        },
+        "buyerControlled": {
+          "type": "boolean"
+        },
+        "collectsPayment": {
+          "const": false,
+          "type": "boolean"
+        },
+        "label": {
+          "type": "string"
+        },
+        "method": {
+          "anyOf": [
+            {
+              "const": "GET",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "placesOrder": {
+          "const": false,
+          "type": "boolean"
+        },
+        "shopperFacing": {
+          "type": "boolean"
+        },
+        "type": {
+          "enum": [
+            "view_exact_product",
+            "open_cart",
+            "request_consultation",
+            "inspect_evidence"
+          ],
+          "type": "string"
+        },
+        "url": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "type",
+        "label",
+        "url",
+        "method",
+        "available",
+        "shopperFacing",
+        "buyerControlled",
+        "placesOrder",
+        "collectsPayment"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / shopperAction

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "available": {
+          "type": "boolean"
+        },
+        "buyerControlled": {
+          "type": "boolean"
+        },
+        "collectsPayment": {
+          "const": false,
+          "type": "boolean"
+        },
+        "label": {
+          "type": "string"
+        },
+        "method": {
+          "anyOf": [
+            {
+              "const": "GET",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "placesOrder": {
+          "const": false,
+          "type": "boolean"
+        },
+        "shopperFacing": {
+          "type": "boolean"
+        },
+        "type": {
+          "enum": [
+            "view_exact_product",
+            "open_cart",
+            "request_consultation",
+            "inspect_evidence"
+          ],
+          "type": "string"
+        },
+        "url": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "type",
+        "label",
+        "url",
+        "method",
+        "available",
+        "shopperFacing",
+        "buyerControlled",
+        "placesOrder",
+        "collectsPayment"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "product",
-  "productHandle",
-  "variantId",
-  "sku",
-  "configuration",
-  "availability",
-  "price",
-  "media",
-  "primaryMedia",
-  "commerceLinks",
-  "purchaseState",
-  "shopperActions",
-  "shopperHandoffPolicy",
-  "checkoutEligibility",
-  "technicalFacts",
-  "requiredDisclosures",
-  "boundaries"
-]New value: +[
+  "product",
+  "productHandle",
+  "variantId",
+  "sku",
+  "configuration",
+  "availability",
+  "price",
+  "media",
+  "primaryMedia",
+  "commerceLinks",
+  "purchaseState",
+  "actionBindings",
+  "inspectionAction",
+  "shopperAction",
+  "referenceAction",
+  "shopperActions",
+  "shopperHandoffPolicy",
+  "checkoutEligibility",
+  "technicalFacts",
+  "requiredDisclosures",
+  "boundaries"
+]

Changed5 schema fields changedSep 5, 2026

addedOutput schema / properties / shopperHandoffPolicy / properties / cartDoesNotReplaceProductPresentation
```
Added value: +{
+  "const": true,
+  "type": "boolean"
+}
```
addedOutput schema / properties / shopperHandoffPolicy / properties / mediaFailureInstruction
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / shopperHandoffPolicy / properties / mediaRequiredBeforePurchaseHandoff
```
Added value: +{
+  "const": true,
+  "type": "boolean"
+}
```

addedOutput schema / properties / shopperHandoffPolicy / properties / presentationSequence

Added value: +{
+  "prefixItems": [
+    {
+      "const": "presentMedia",
+      "type": "string"
+    },
+    {
+      "const": "presentFactsAndDisclosures",
+      "type": "string"
+    },
+    {
+      "const": "offerPurchaseHandoff",
+      "type": "string"
+    }
+  ],
+  "type": "array"
+}

changedOutput schema / properties / shopperHandoffPolicy / required

Previous value: -[
-  "groundingRole",
-  "inspectionRole",
-  "purchaseReadyRole",
-  "explicitPurchaseIntentRole",
-  "evidenceIsShopperDestination",
-  "proactiveInstruction",
-  "explicitPurchaseInstruction"
-]New value: +[
+  "groundingRole",
+  "inspectionRole",
+  "purchaseReadyRole",
+  "explicitPurchaseIntentRole",
+  "evidenceIsShopperDestination",
+  "presentationSequence",
+  "mediaRequiredBeforePurchaseHandoff",
+  "cartDoesNotReplaceProductPresentation",
+  "mediaFailureInstruction",
+  "proactiveInstruction",
+  "explicitPurchaseInstruction"
+]

Changed4 schema fields changedSep 4, 2026

addedOutput schema / properties / purchaseState

Added value: +{
+  "enum": [
+    "purchase_ready",
+    "consultation_ready",
+    "view_only"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / shopperActions

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "addToCart": {
+      "additionalProperties": false,
+      "properties": {
+        "available": {
+          "type": "boolean"
+        },
+        "label": {
+          "type": "string"
+        },
+        "method": {
+          "anyOf": [
+            {
+              "const": "GET",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "url": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "available",
+        "url",
+        "method",
+        "label"
+      ],
+      "type": "object"
+    },
+    "requestConsultation": {
+      "additionalProperties": false,
+      "properties": {
+        "available": {
+          "type": "boolean"
+        },
+        "label": {
+          "type": "string"
+        },
+        "method": {
+          "anyOf": [
+            {
+              "const": "GET",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "url": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "available",
+        "url",
+        "method",
+        "label"
+      ],
+      "type": "object"
+    },
+    "startCheckout": {
+      "additionalProperties": false,
+      "properties": {
+        "available": {
+          "type": "boolean"
+        },
+        "label": {
+          "type": "string"
+        },
+        "method": {
+          "anyOf": [
+            {
+              "const": "GET",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "url": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "available",
+        "url",
+        "method",
+        "label"
+      ],
+      "type": "object"
+    },
+    "viewProduct": {
+      "additionalProperties": false,
+      "properties": {
+        "available": {
+          "type": "boolean"
+        },
+        "label": {
+          "type": "string"
+        },
+        "method": {
+          "anyOf": [
+            {
+              "const": "GET",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "url": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "available",
+        "url",
+        "method",
+        "label"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "viewProduct",
+    "addToCart",
+    "startCheckout",
+    "requestConsultation"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / shopperHandoffPolicy

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "evidenceIsShopperDestination": {
+      "const": false,
+      "type": "boolean"
+    },
+    "explicitPurchaseInstruction": {
+      "type": "string"
+    },
+    "explicitPurchaseIntentRole": {
+      "anyOf": [
+        {
+          "enum": [
+            "cartUrl",
+            "requestConsultation"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "groundingRole": {
+      "const": "evidenceUrl",
+      "type": "string"
+    },
+    "inspectionRole": {
+      "const": "customerUrl",
+      "type": "string"
+    },
+    "proactiveInstruction": {
+      "type": "string"
+    },
+    "purchaseReadyRole": {
+      "anyOf": [
+        {
+          "enum": [
+            "cartUrl",
+            "requestConsultation"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "groundingRole",
+    "inspectionRole",
+    "purchaseReadyRole",
+    "explicitPurchaseIntentRole",
+    "evidenceIsShopperDestination",
+    "proactiveInstruction",
+    "explicitPurchaseInstruction"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "product",
-  "productHandle",
-  "variantId",
-  "sku",
-  "configuration",
-  "availability",
-  "price",
-  "media",
-  "primaryMedia",
-  "commerceLinks",
-  "checkoutEligibility",
-  "technicalFacts",
-  "requiredDisclosures",
-  "boundaries"
-]New value: +[
+  "product",
+  "productHandle",
+  "variantId",
+  "sku",
+  "configuration",
+  "availability",
+  "price",
+  "media",
+  "primaryMedia",
+  "commerceLinks",
+  "purchaseState",
+  "shopperActions",
+  "shopperHandoffPolicy",
+  "checkoutEligibility",
+  "technicalFacts",
+  "requiredDisclosures",
+  "boundaries"
+]

Changed8 schema fields changedSep 4, 2026

addedOutput schema / properties / commerceLinks / properties / cartUrl

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / commerceLinks / properties / checkoutUrl
```
Added value: +{
+  "type": "null"
+}
```
addedOutput schema / properties / commerceLinks / properties / customerUrl
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / commerceLinks / properties / evidenceUrl

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / properties / commerceLinks / required

Previous value: -[
-  "canonicalProductUrl",
-  "exactVariantProductUrl",
-  "attributedProductUrl",
-  "shopifyCartPermalink",
-  "attributedCartPermalink"
-]New value: +[
+  "evidenceUrl",
+  "customerUrl",
+  "cartUrl",
+  "checkoutUrl",
+  "canonicalProductUrl",
+  "exactVariantProductUrl",
+  "attributedProductUrl",
+  "shopifyCartPermalink",
+  "attributedCartPermalink"
+]

addedOutput schema / properties / technicalFacts / properties / burner

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "btuOutput": {
+      "type": "null"
+    },
+    "btuOutputConfirmed": {
+      "const": false,
+      "type": "boolean"
+    },
+    "csaStatus": {
+      "type": "null"
+    },
+    "csaStatusConfirmed": {
+      "const": false,
+      "type": "boolean"
+    },
+    "inclusionConfirmed": {
+      "const": false,
+      "type": "boolean"
+    },
+    "manufacturer": {
+      "type": "null"
+    },
+    "manufacturerConfirmed": {
+      "const": false,
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "inclusionConfirmed",
+    "manufacturerConfirmed",
+    "manufacturer",
+    "btuOutputConfirmed",
+    "btuOutput",
+    "csaStatusConfirmed",
+    "csaStatus"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / technicalFacts / properties / warranty

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "guidance": {
+      "type": "string"
+    },
+    "termsConfirmedForExactConfiguration": {
+      "const": false,
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "termsConfirmedForExactConfiguration",
+    "guidance"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / technicalFacts / required

Previous value: -[
-  "source",
-  "roundDiameterInches",
-  "diameterInches",
-  "ignition",
-  "includedItems",
-  "cover",
-  "fulfillment",
-  "shipping",
-  "gasInstallation"
-]New value: +[
+  "source",
+  "roundDiameterInches",
+  "diameterInches",
+  "ignition",
+  "includedItems",
+  "cover",
+  "burner",
+  "warranty",
+  "fulfillment",
+  "shipping",
+  "gasInstallation"
+]

First observedSep 1, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the annotations, it discloses the required presentation sequence, the mandatory media handling, the fallback when images cannot render, the roles of evidenceUrl and customerUrl, event-queue recording, and the hard limitation that no order or payment can be collected. None of this contradicts the idempotentHint or readOnlyHint 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 dense but every sentence or clause carries a distinct operational rule: confirmation gate, exactly-once call, media requirement, display order, cart handoff, optional URLs, event capture, and order/payment boundary. The critical precondition is front-loaded, and there is no filler.

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 workflow-heavy configuration tool, the description fully covers prerequisites, call frequency, presentation sequence, failure handling, URL usage, side effects, and limitations. Since an output schema exists, return-value details do not need to be restated, and no essential behavioral 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?

The schema already documents all four parameters with enums and explicit 'never infer' instructions, so schema coverage is 100%. The description repeats the parameter names in prose but does not add new semantic detail about values, formats, or relationships, keeping it at the baseline for full schema coverage.

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 action: resolve an exact Homebridge fire-pit configuration against the live Shopify catalog only after the buyer has confirmed all four selections. It also distinguishes this as the final completed-selection step, not a qualification, variant resolution, media display, or checkout tool.

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?

It provides explicit preconditions (buyer must state and confirm all four attributes), a clear never-rule (never infer a missing selection), and a call-count rule (exactly once for the completed selection). It also defines when cartUrl should be offered, when it must be used directly, and what the tool cannot do, such as placing an order or creating authenticated checkout.

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 tools Inspect

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

Need Help?