Samuelz® Policy

Katalogänderung prüfen

prepare_business_catalog_change

Read-onlyIdempotent

After explicit request, copy exact expectedRevision and identity from get_business_catalog; preserve fields from read. supplier_areas requires additional crm:read/crm:write authority: copy a service-area id and exact supplierIds from supplierOptions; adoptions may include only canAdopt options with their exact rankedMarket. It atomically connects those ranked suppliers and replaces area assignments, without changing global supplier status or confirming qualifications. Optional offer locales patch localized fields; omitted fields remain unchanged. Use business_field, business_brand, offer_version, publish_offer or withdraw_offer for the shared configured sale model. Copy their IDs and expectedRevision/expectedVersion from commerceModel. A version freezes the explicit price, tax, terms, brand and fulfillment; publication is a separate exact human approval. These actions use the same central functions as the owner UI. Existing module-managed offers retain their module adapter. Archive checks dependencies. Preview never writes; use show_business_catalog_approval with identical input. Stale revisions require reread and renewed intent.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "expectedRevision": "<expectedRevision>",
      "change": "<change>"
    },
    "name": "prepare_business_catalog_change"
  }
}

Input Schema

Name	Required	Description	Default
`change`	Yes
`expectedRevision`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 11, 2026

changedInput schema / properties / change / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "adoptions": {
-        "default": [],
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "market": {
-              "maxLength": 120,
-              "minLength": 1,
-              "type": "string"
-            },
-            "supplierId": {
-              "maxLength": 160,
-              "minLength": 1,
-              "type": "string"
-            }
-          },
-          "required": [
-            "supplierId",
-            "market"
-          ],
-          "type": "object"
-        },
-        "maxItems": 20,
-        "type": "array"
-      },
-      "id": {
-        "maxLength": 160,
-        "type": "string"
-      },
-      "supplierIds": {
-        "items": {
-          "maxLength": 160,
-          "minLength": 1,
-          "type": "string"
-        },
-        "maxItems": 500,
-        "type": "array"
-      },
-      "type": {
-        "const": "supplier_areas",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "id",
-      "supplierIds"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "id": {
-        "pattern": "^business_place:[a-z0-9:_-]{1,80}$",
-        "type": "string"
-      },
-      "type": {
-        "const": "place",
-        "type": "string"
-      },
-      "value": {
-        "additionalProperties": false,
-        "properties": {
-          "countryCode": {
-            "maxLength": 2,
-            "type": "string"
-          },
-          "labels": {
-            "additionalProperties": {
-              "maxLength": 160,
-              "minLength": 1,
-              "type": "string"
-            },
-            "propertyNames": {
-              "pattern": "^[a-z]{2}$",
-              "type": "string"
-            },
-            "type": "object"
-          },
-          "locality": {
-            "maxLength": 160,
-            "type": "string"
-          },
-          "postalCode": {
-            "maxLength": 32,
-            "type": "string"
-          },
-          "routingAliases": {
-            "items": {
-              "maxLength": 160,
-              "minLength": 3,
-              "type": "string"
-            },
-            "maxItems": 40,
-            "type": "array"
-          },
-          "streetAddress": {
-            "maxLength": 240,
-            "type": "string"
-          },
-          "timezone": {
-            "maxLength": 80,
-            "type": "string"
-          },
-          "usage": {
-            "enum": [
-              "primary_location",
-              "service_area"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "usage",
-          "countryCode",
-          "locality",
-          "postalCode",
-          "streetAddress",
-          "timezone",
-          "labels"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "type",
-      "id",
-      "value"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "key": {
-        "pattern": "^[a-z0-9][a-z0-9:_-]{0,159}$",
-        "type": "string"
-      },
-      "type": {
-        "const": "offer",
-        "type": "string"
-      },
-      "value": {
-        "additionalProperties": false,
-        "properties": {
-          "actionLabel": {
-            "maxLength": 100,
-            "type": "string"
-          },
-          "actionUrl": {
-            "maxLength": 2048,
-            "type": "string"
-          },
-          "category": {
-            "maxLength": 80,
-            "type": "string"
-          },
-          "defaultLocale": {
-            "pattern": "^[a-z]{2}$",
-            "type": "string"
-          },
-          "kind": {
-            "enum": [
-              "product",
-              "service"
-            ],
-            "type": "string"
-          },
-          "locales": {
-            "additionalProperties": {
-              "additionalProperties": false,
-              "properties": {
-                "actionLabel": {
-                  "maxLength": 100,
-                  "minLength": 1,
-                  "type": "string"
-                },
-                "actionUrl": {
-                  "maxLength": 2048,
-                  "minLength": 1,
-                  "type": "string"
-                },
-                "summary": {
-                  "maxLength": 800,
-                  "minLength": 1,
-                  "type": "string"
-                },
-                "title": {
-                  "maxLength": 160,
-                  "minLength": 1,
-                  "type": "string"
-                }
-              },
-              "type": "object"
-            },
-            "propertyNames": {
-              "pattern": "^[a-z]{2}(?:-[a-z]{2})?$",
-              "type": "string"
-            },
-            "type": "object"
-          },
-          "locationKey": {
-            "maxLength": 100,
-            "type": "string"
-          },
-          "rateResourceId": {
-            "maxLength": 100,
-            "type": "string"
-          },
-          "summary": {
-            "maxLength": 800,
-            "type": "string"
-          },
-          "title": {
-            "maxLength": 160,
-            "type": "string"
-          }
-        },
-        "required": [
-          "kind",
-          "category",
-          "title",
-          "summary",
-          "actionLabel",
-          "actionUrl",
-          "locationKey",
-          "rateResourceId",
-          "defaultLocale"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "type",
-      "key",
-      "value"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "id": {
-        "maxLength": 100,
-        "type": "string"
-      },
-      "type": {
-        "enum": [
-          "archive_place",
-          "delete_place"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "id"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "key": {
-        "maxLength": 160,
-        "type": "string"
-      },
-      "type": {
-        "enum": [
-          "archive_offer",
-          "delete_offer"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "key"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "type": {
+        "const": "business_field",
+        "type": "string"
+      },
+      "value": {
+        "additionalProperties": false,
+        "properties": {
+          "audience": {
+            "maxLength": 2000,
+            "minLength": 1,
+            "type": "string"
+          },
+          "businessModel": {
+            "maxLength": 2000,
+            "minLength": 1,
+            "type": "string"
+          },
+          "economicRef": {
+            "maxLength": 200,
+            "minLength": 1,
+            "type": "string"
+          },
+          "expectedRevision": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "key": {
+            "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$",
+            "type": "string"
+          },
+          "market": {
+            "maxLength": 2000,
+            "minLength": 1,
+            "type": "string"
+          },
+          "name": {
+            "maxLength": 160,
+            "minLength": 1,
+            "type": "string"
+          },
+          "requestKey": {
+            "maxLength": 160,
+            "minLength": 1,
+            "type": "string"
+          },
+          "status": {
+            "enum": [
+              "draft",
+              "active",
+              "archived"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "key",
+          "name",
+          "audience",
+          "market",
+          "businessModel",
+          "economicRef",
+          "status",
+          "expectedRevision",
+          "requestKey"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "type",
+      "value"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "type": {
+        "const": "business_brand",
+        "type": "string"
+      },
+      "value": {
+        "additionalProperties": false,
+        "properties": {
+          "expectedRevision": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "host": {
+            "maxLength": 253,
+            "type": "string"
+          },
+          "key": {
+            "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$",
+            "type": "string"
+          },
+          "name": {
+            "maxLength": 160,
+            "minLength": 1,
+            "type": "string"
+          },
+          "presentation": {
+            "additionalProperties": false,
+            "properties": {
+              "accentHex": {
+                "pattern": "^#[a-fA-F0-9]{6}$",
+                "type": "string"
+              },
+              "primaryHex": {
+                "pattern": "^#[a-fA-F0-9]{6}$",
+                "type": "string"
+              },
+              "tagline": {
+                "maxLength": 500,
+                "type": "string"
+              }
+            },
+            "required": [
+              "primaryHex",
+              "accentHex",
+              "tagline"
+            ],
+            "type": "object"
+          },
+          "requestKey": {
+            "maxLength": 160,
+            "minLength": 1,
+            "type": "string"
+          },
+          "senderAddress": {
+            "format": "email",
+            "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
+            "type": "string"
+          },
+          "siteId": {
+            "maxLength": 200,
+            "minLength": 1,
+            "type": "string"
+          },
+          "status": {
+            "enum": [
+              "draft",
+              "active",
+              "archived"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "key",
+          "name",
+          "presentation",
+          "siteId",
+          "host",
+          "senderAddress",
+          "status",
+          "expectedRevision",
+          "requestKey"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "type",
+      "value"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "type": {
+        "const": "offer_version",
+        "type": "string"
+      },
+      "value": {
+        "additionalProperties": false,
+        "properties": {
+          "brandId": {
+            "maxLength": 200,
+            "minLength": 1,
+            "type": "string"
+          },
+          "contract": {
+            "additionalProperties": false,
+            "properties": {
+              "buyerCountryCodes": {
+                "items": {
+                  "pattern": "^[A-Z]{2}$",
+                  "type": "string"
+                },
+                "maxItems": 250,
+                "minItems": 1,
+                "type": "array"
+              },
+              "checkoutMinutes": {
+                "maximum": 1440,
+                "minimum": 60,
+                "type": "integer"
+              },
+              "currency": {
+                "pattern": "^[A-Z]{3}$",
+                "type": "string"
+              },
+              "fulfillment": {
+                "oneOf": [
+                  {
+                    "additionalProperties": false,
+                    "properties": {
+                      "accessDays": {
+                        "maximum": 3650,
+                        "minimum": 1,
+                        "type": "integer"
+                      },
+                      "deliveryWithinHours": {
+                        "maximum": 8760,
+                        "minimum": 1,
+                        "type": "integer"
+                      },
+                      "kind": {
+                        "const": "digital_file",
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "deliveryWithinHours",
+                      "accessDays"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "additionalProperties": false,
+                    "properties": {
+                      "kind": {
+                        "const": "scheduled_service",
+                        "type": "string"
+                      },
+                      "resourceId": {
+                        "maxLength": 200,
+                        "minLength": 1,
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "resourceId"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "additionalProperties": false,
+                    "properties": {
+                      "kind": {
+                        "const": "appointment",
+                        "type": "string"
+                      },
+                      "resourceId": {
+                        "maxLength": 200,
+                        "minLength": 1,
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "resourceId"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "additionalProperties": false,
+                    "properties": {
+                      "kind": {
+                        "const": "physical_delivery",
+                        "type": "string"
+                      },
+                      "workflowKey": {
+                        "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$",
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "workflowKey"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "additionalProperties": false,
+                    "properties": {
+                      "kind": {
+                        "const": "workflow",
+                        "type": "string"
+                      },
+                      "workflowKey": {
+                        "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$",
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "workflowKey"
+                    ],
+                    "type": "object"
+                  }
+                ]
+              },
+              "grossAmountMinor": {
+                "exclusiveMinimum": 0,
+                "maximum": 100000000000,
+                "type": "integer"
+              },
+              "payment": {
+                "oneOf": [
+                  {
+                    "additionalProperties": false,
+                    "properties": {
+                      "kind": {
+                        "const": "prepaid",
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "additionalProperties": false,
+                    "properties": {
+                      "kind": {
+                        "const": "on_site",
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind"
+                    ],
+                    "type": "object"
+                  }
+                ]
+              },
+              "scope": {
+                "maxLength": 6000,
+                "minLength": 1,
+                "type": "string"
+              },
+              "tax": {
+                "additionalProperties": false,
+                "properties": {
+                  "categoryCode": {
+                    "enum": [
+                      "S",
+                      "Z",
+                      "E",
+                      "AE",
+                      "K"
+                    ],
+                    "type": "string"
+                  },
+                  "decisionReference": {
+                    "maxLength": 500,
+                    "minLength": 1,
+                    "type": "string"
+                  },
+                  "exemptionReason": {
+                    "maxLength": 1000,
+                    "minLength": 1,
+                    "type": "string"
+                  },
+                  "rateBasisPoints": {
+                    "maximum": 10000,
+                    "minimum": 0,
+                    "type": "integer"
+                  }
+                },
+                "required": [
+                  "categoryCode",
+                  "rateBasisPoints"
+                ],
+                "type": "object"
+              },
+              "terms": {
+                "maxLength": 6000,
+                "minLength": 1,
+                "type": "string"
+              },
+              "title": {
+                "maxLength": 160,
+                "minLength": 1,
+                "type": "string"
+              }
+            },
+            "required": [
+              "title",
+              "scope",
+              "grossAmountMinor",
+              "currency",
+              "tax",
+              "checkoutMinutes",
+              "buyerCountryCodes",
+              "payment",
+              "terms",
+              "fulfillment"
+            ],
+            "type": "object"
+          },
+          "expectedVersion": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "fieldId": {
+            "maxLength": 200,
+            "minLength": 1,
+            "type": "string"
+          },
+          "offerKey": {
+            "maxLength": 160,
+            "minLength": 1,
+            "type": "string"
+          },
+          "requestKey": {
+            "maxLength": 160,
+            "minLength": 1,
+            "type": "string"
+          },
+          "reviewed": {
+            "const": true,
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "offerKey",
+          "fieldId",
+          "brandId",
+          "contract",
+          "expectedVersion",
+          "requestKey",
+          "reviewed"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "type",
+      "value"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "type": {
+        "const": "publish_offer",
+        "type": "string"
+      },
+      "value": {
+        "additionalProperties": false,
+        "properties": {
+          "expectedRevision": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "requestKey": {
+            "maxLength": 140,
+            "minLength": 1,
+            "type": "string"
+          },
+          "reviewed": {
+            "const": true,
+            "type": "boolean"
+          },
+          "versionId": {
+            "maxLength": 200,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "versionId",
+          "expectedRevision",
+          "requestKey",
+          "reviewed"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "type",
+      "value"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "type": {
+        "const": "withdraw_offer",
+        "type": "string"
+      },
+      "value": {
+        "additionalProperties": false,
+        "properties": {
+          "expectedRevision": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "requestKey": {
+            "maxLength": 140,
+            "minLength": 1,
+            "type": "string"
+          },
+          "reviewed": {
+            "const": true,
+            "type": "boolean"
+          },
+          "versionId": {
+            "maxLength": 200,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "versionId",
+          "expectedRevision",
+          "requestKey",
+          "reviewed"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "type",
+      "value"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "adoptions": {
+        "default": [],
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "market": {
+              "maxLength": 120,
+              "minLength": 1,
+              "type": "string"
+            },
+            "supplierId": {
+              "maxLength": 160,
+              "minLength": 1,
+              "type": "string"
+            }
+          },
+          "required": [
+            "supplierId",
+            "market"
+          ],
+          "type": "object"
+        },
+        "maxItems": 20,
+        "type": "array"
+      },
+      "id": {
+        "maxLength": 160,
+        "type": "string"
+      },
+      "supplierIds": {
+        "items": {
+          "maxLength": 160,
+          "minLength": 1,
+          "type": "string"
+        },
+        "maxItems": 500,
+        "type": "array"
+      },
+      "type": {
+        "const": "supplier_areas",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "id",
+      "supplierIds"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "pattern": "^business_place:[a-z0-9:_-]{1,80}$",
+        "type": "string"
+      },
+      "type": {
+        "const": "place",
+        "type": "string"
+      },
+      "value": {
+        "additionalProperties": false,
+        "properties": {
+          "countryCode": {
+            "maxLength": 2,
+            "type": "string"
+          },
+          "labels": {
+            "additionalProperties": {
+              "maxLength": 160,
+              "minLength": 1,
+              "type": "string"
+            },
+            "propertyNames": {
+              "pattern": "^[a-z]{2}$",
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "locality": {
+            "maxLength": 160,
+            "type": "string"
+          },
+          "postalCode": {
+            "maxLength": 32,
+            "type": "string"
+          },
+          "routingAliases": {
+            "items": {
+              "maxLength": 160,
+              "minLength": 3,
+              "type": "string"
+            },
+            "maxItems": 40,
+            "type": "array"
+          },
+          "streetAddress": {
+            "maxLength": 240,
+            "type": "string"
+          },
+          "timezone": {
+            "maxLength": 80,
+            "type": "string"
+          },
+          "usage": {
+            "enum": [
+              "primary_location",
+              "service_area"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "usage",
+          "countryCode",
+          "locality",
+          "postalCode",
+          "streetAddress",
+          "timezone",
+          "labels"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "type",
+      "id",
+      "value"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "key": {
+        "pattern": "^[a-z0-9][a-z0-9:_-]{0,159}$",
+        "type": "string"
+      },
+      "type": {
+        "const": "offer",
+        "type": "string"
+      },
+      "value": {
+        "additionalProperties": false,
+        "properties": {
+          "actionLabel": {
+            "maxLength": 100,
+            "type": "string"
+          },
+          "actionUrl": {
+            "maxLength": 2048,
+            "type": "string"
+          },
+          "category": {
+            "maxLength": 80,
+            "type": "string"
+          },
+          "defaultLocale": {
+            "pattern": "^[a-z]{2}$",
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "product",
+              "service"
+            ],
+            "type": "string"
+          },
+          "locales": {
+            "additionalProperties": {
+              "additionalProperties": false,
+              "properties": {
+                "actionLabel": {
+                  "maxLength": 100,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "actionUrl": {
+                  "maxLength": 2048,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "summary": {
+                  "maxLength": 800,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "title": {
+                  "maxLength": 160,
+                  "minLength": 1,
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "propertyNames": {
+              "pattern": "^[a-z]{2}(?:-[a-z]{2})?$",
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "locationKey": {
+            "maxLength": 100,
+            "type": "string"
+          },
+          "rateResourceId": {
+            "maxLength": 100,
+            "type": "string"
+          },
+          "summary": {
+            "maxLength": 800,
+            "type": "string"
+          },
+          "title": {
+            "maxLength": 160,
+            "type": "string"
+          }
+        },
+        "required": [
+          "kind",
+          "category",
+          "title",
+          "summary",
+          "actionLabel",
+          "actionUrl",
+          "locationKey",
+          "rateResourceId",
+          "defaultLocale"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "type",
+      "key",
+      "value"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "maxLength": 100,
+        "type": "string"
+      },
+      "type": {
+        "enum": [
+          "archive_place",
+          "delete_place"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "id"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "key": {
+        "maxLength": 160,
+        "type": "string"
+      },
+      "type": {
+        "enum": [
+          "archive_offer",
+          "delete_offer"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "key"
+    ],
+    "type": "object"
+  }
+]

First observedNov 11, 2026

TDQS

B3.2/5.0

Behavior3/5

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

Beyond the readOnly/destructive/idempotent annotations, the description adds genuine behavioral context: the crm:read/crm:write authority needed for supplier_areas, that archive actions check dependencies, that publication is a separate exact human approval, and that stale revisions force a reread. But it also says the tool 'atomically connects those ranked suppliers and replaces area assignments', which reads like mutation before the later 'Preview never writes' qualifies it, muddying the write/no-write story that annotations try to settle.

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

Conciseness3/5

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

Length is defensible for a tool whose schema is a nine-branch union, and most sentences carry information. But it is a semicolon-chained wall that opens with an input-copying instruction rather than the tool's purpose, and unrelated constraints (permissions, locales, freezing, module adapters, archive checks, preview) are packed without ordering or grouping.

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

Completeness3/5

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

For a high-complexity preview tool with no output schema and zero schema field descriptions, the definition covers permissions, revision sourcing, approval handoff, and staleness handling, which is meaningful. It still omits what a successful call yields and leaves several union branches and the 'never writes yet atomically connects' tension unexplained, so an agent cannot fully predict behavior for all change types.

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 0%, so the description must carry the semantic load; it does explain sourcing for expectedRevision (from get_business_catalog or expectedVersion from commerceModel) and constrains supplier_areas (copy a service-area id, exact supplierIds, adoptions only from canAdopt with their exact rankedMarket) and optional offer locales patching. Several union branches (place, offer, archive_place/delete_place, archive_offer/delete_offer) get no semantic guidance at all, and phrases like 'preserve fields from read' stay vague given the schema's nine oneOf variants.

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

Purpose3/5

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

The description enumerates the supported change types and the sources to copy identifiers from, and near the end states 'Preview never writes', so an agent can infer that this prepares/validates a business catalog change. However, it never plainly states the core action (prepare a catalog change for later confirmation); the purpose has to be assembled from fragments about revisions, suppliers, and offers rather than from a clear verb+resource statement.

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 gives real routing guidance: 'After explicit request' establishes the prerequisite, 'Use business_field, business_brand, offer_version, publish_offer or withdraw_offer for the shared configured sale model' tells the agent which union branch fits, and 'use show_business_catalog_approval with identical input' names the follow-up sibling. 'Stale revisions require reread and renewed intent' adds an explicit recovery path. It stops short of explicit when-not-to-use conditions or naming a confirm/prepare alternative.

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

All Samuelz® Policy 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?