Skip to main content
Glama

Edit shop

shop_write
Destructive

Creates and updates shop categories, products, product images, variations, stock, basket and checkout, orders and their status, payment method and delivery, product comments and currency rates. No action takes or sends money through a payment system: placing an order or changing its payment method charges nothing (the new method may also set the payment processing status), a paid order status is set without a payment, and order status changes may credit or debit the internal shop balances of buyers, user sellers and referrers kept on the site; there is no action that sets or changes a balance directly.

Input Schema

NameRequiredDescriptionDefault
idNoGoods, category, comment, or basket line id.
artNoSKU / article.
cntNoBasket quantity.
idsNoIds separated by commas (invoice_*: order ids, also separated by |; stock_remove).
imgNoImage slot number, 0 for the main image.
nowNo1 = buy now.
optNoSelected options OPTION_ID-VALUE_ID:… for basket/order.
pidNoParent category id.
posNoCategory position.
urlNoCustom URL slug.
consNo
dscrNoFull description; pass html_dscr=1 when HTML.
hideNoHide flag or invoices_list group.
modeNocheckout_update mode.
nameNoGoods or category name.
noteNo
prosNo
tagsNo
typeNoGoods type: 0 material, 1 file, 2 e-code, 3 service.
unitNo
warrNo
brandNoBrand.
briefNoShort description.
orderNoList asc/desc or order hash.
priceNoPrice (goods or variation_update).
soldsNo
stockNoStock count.
viewsNo
actionYesOperation to run. Each oneOf entry describes one action and lists its parameters.
cat_idNoGoods category id (add/update).
fieldsNoExtra form keys (checkout field_N, stock_*, var_*, cnt_REC_ID, …). Routing and mode keys (method, mode, del, page, …) are ignored.
imagesNoFiles for img_add (remote upload). Each item is { filename, content_base64 }, { upload_id }, or { site_path }. Appended as file_add_N after the image_*/file_* slots.
statusNoOrder status code.
undiscNo
valuesNoVariation dictionary values, comma-separated (S,M,L).
weightNo
confirmNoPass true only after the user approves this change. Required by: img_edit, variation_gen, checkout_submit, invoice_status, invoice_payment.
messageNoComment text.
opt_selNoOption set for stock_add (e.g. 2-3:4).
orderedNo
stock_qNo
user_idNoUser id filter or balance target.
cats_addNoExtra category ids [ID1, ID2, …].
entry_idNoGoods id for comments_add.
price_inNoPurchase price.
rate_numNo
rate_sumNo
ch_addcatNo1 when cats_add is passed.
curr_codeNo
curr_rateNo
file_pathNoSynonym for image_path (local MCP server path).
html_dscrNo1 = dscr is HTML.
meta_dscrNo
parent_idNoSynonym for pid / category_list parent.
price_oldNoOld price.
add_groupsNo
global_catNo
image_pathNoLocal MCP server path for image upload. Missing files are an error; remote agents must use image_base64, image_upload_id, or image_site_path.
meta_titleNo
payment_idNo
promo_codeNo
delivery_idNo
file_base64NoSynonym for image_base64.
image_pathsNoComma-separated local MCP server paths (img_add). Missing files are an error.
view_groupsNo
file_add_cntNo
image_base64NoBase64 image body with image_filename (remote upload). Wins over image_upload_id, image_site_path, and image_path.
file_filenameNoSynonym for image_filename.
group_courierNo
variation_crcNoVariation hash from variations_list.
file_site_pathNoSynonym for image_site_path.
file_upload_idNoSynonym for image_upload_id.
image_filenameNoFile name for image_base64, with extension.
image_site_pathNoFile already on the site (img/x.jpg or its full site URL). Wins over image_path.
image_upload_idNoupload_id from upload_direct. Wins over image_site_path and image_path.
image_site_pathsNoComma-separated site files for img_add (img/x.jpg or full site URLs).
image_upload_idsNoComma-separated upload_id values from upload_direct for img_add.
custom_delivery_taxNo
subscribe_to_repliesNo
exclude_from_discountNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / action / oneOf
      Previous value: -[
      -  {
      -    "const": "category_add",
      -    "description": "Creates a category, with an image when an image slot is filled. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Optional: name, pid, parent_id, global_cat, dscr, brief, meta_title, meta_dscr, url, pos, view_groups, add_groups, exclude_from_discount, fields, image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path."
      -  },
      -  {
      -    "const": "category_update",
      -    "description": "Updates a category; a filled image slot replaces its image. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). The current image is removed before the new one is saved, so a file with such an extension that is not a valid image leaves the category without an image. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: name, pid, parent_id, global_cat, dscr, brief, meta_title, meta_dscr, url, pos, view_groups, add_groups, exclude_from_discount, fields, image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path."
      -  },
      -  {
      -    "const": "category_show",
      -    "description": "Shows a hidden category. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "category_hide",
      -    "description": "Hides a category. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "category_image",
      -    "description": "Uploads the image of a category from the first filled image slot. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). The current image is removed before the new one is saved, so a file with such an extension that is not a valid image leaves the category without an image. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, fields."
      -  },
      -  {
      -    "const": "add",
      -    "description": "Creates a product. Optional: cat_id, name, brief, dscr, html_dscr, price, price_in, price_old, stock, art, brand, url, meta_title, meta_dscr, tags, type, cats_add, ch_addcat, unit, weight, warr, undisc, fields."
      -  },
      -  {
      -    "const": "update",
      -    "description": "Updates a product. Required: id. Optional: cat_id, name, brief, dscr, html_dscr, price, price_in, price_old, stock, art, brand, url, meta_title, meta_dscr, tags, type, cats_add, ch_addcat, unit, weight, warr, undisc, fields."
      -  },
      -  {
      -    "const": "hide",
      -    "description": "Hides or shows a product. Required: id. Optional: hide, fields."
      -  },
      -  {
      -    "const": "cnt_save",
      -    "description": "Saves product counters (views, sales, orders, rating, stock). Required: id. Optional: views, solds, ordered, rate_num, rate_sum, stock_q, fields."
      -  },
      -  {
      -    "const": "img_add",
      -    "description": "Adds images to a product. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, image_paths, image_upload_ids, image_site_paths, images, file_add_cnt, fields."
      -  },
      -  {
      -    "const": "img_edit",
      -    "description": "Replaces the product image in slot img (0 is the main image; the slot must already hold an image). The new image can keep the URL of the old one. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id, img, confirm. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, fields."
      -  },
      -  {
      -    "const": "variation_update",
      -    "description": "Updates one variation of a product. Required: id, variation_crc. Optional: art, stock, price, price_old, weight, fields."
      -  },
      -  {
      -    "const": "variation_dict_save",
      -    "description": "Creates a variation dictionary (name and values), or updates the dictionary id: a new name and/or the full list of values. Optional: id, name, values, fields."
      -  },
      -  {
      -    "const": "variation_load",
      -    "description": "Loads the variations of a product into its edit form. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "variation_gen",
      -    "description": "Generates product variations from var_* keys in fields. Required: id, confirm. Optional: fields."
      -  },
      -  {
      -    "const": "variation_edit_save",
      -    "description": "Saves product variations from var_* keys in fields. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "stock_genall",
      -    "description": "Generates all option sets of a product stock. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "stock_add",
      -    "description": "Adds an option set to a product stock. Required: id, opt_sel. Optional: fields."
      -  },
      -  {
      -    "const": "stock_save",
      -    "description": "Saves product stock from stock_* keys in fields. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "basket_add",
      -    "description": "Adds a product to the basket. Required: id. Optional: cnt, opt, now, fields."
      -  },
      -  {
      -    "const": "basket_update",
      -    "description": "Changes the quantity of a basket line. Required: id. Optional: cnt, opt, now, fields."
      -  },
      -  {
      -    "const": "checkout_update",
      -    "description": "Recalculates or changes the unfinished order (mode recalc or change; checkout field_N keys in fields). Required: mode. Optional: fields."
      -  },
      -  {
      -    "const": "checkout_submit",
      -    "description": "Places the order from the basket and sends the order notices. No payment is taken: the order waits for payment by the chosen method. Required: confirm. Optional: payment_id, delivery_id, promo_code, custom_delivery_tax, fields."
      -  },
      -  {
      -    "const": "invoice_hide",
      -    "description": "Moves orders to an order group. Optional: ids, id, hide, fields."
      -  },
      -  {
      -    "const": "invoice_courier",
      -    "description": "Assigns a courier to orders. Required: group_courier. Optional: ids, id, fields."
      -  },
      -  {
      -    "const": "invoice_status",
      -    "description": "Sets the status of orders; a paid status is set without any payment. When the shop returns cancelled payments to the balance, moving an order that a registered buyer actually paid online or from the balance from a paid status (2-8) to new, awaiting payment, cancelled or payment processing credits its total to the internal shop balance of the buyer; the buyer gets nothing back for an order that was never paid online or from the balance. Whether a later return to a paid status debits the credited total depends on the status history of the order: it may not be debited, repeated status changes may credit it again, and with some shop settings it may be debited again. Moving an order between the delivered or completed statuses and any other status also credits or debits the internal balances of the user sellers of its goods and the Telegram shop referrer reward, when those are in use, whether or not the order was paid; a move between delivered and completed changes nothing. Required: status, confirm. Optional: ids, id, fields."
      -  },
      -  {
      -    "const": "invoice_payment",
      -    "description": "Changes the payment method of an order that can still be paid (order hash in order or id); no payment is taken. When the new method is set up so, the order also gets the payment processing status, which can credit or debit internal balances as in invoice_status. The reply may carry the order link and the payment form of the new method for the buyer. Required: payment_id, confirm. Optional: order, id, fields."
      -  },
      -  {
      -    "const": "order_update",
      -    "description": "Changes the goods of an order: quantities, options and prices of its lines, or removes lines (keys in fields). The order total is recalculated, and that total is what may later go back to the balance of the buyer on cancellation. The status and note values are not applied: use invoice_status for the status. Required: order. Optional: status, note, fields."
      -  },
      -  {
      -    "const": "order_add_goods",
      -    "description": "Adds goods to an order. Required: order. Optional: fields."
      -  },
      -  {
      -    "const": "order_delivery_tax",
      -    "description": "Sets a custom delivery cost of an order. Required: order, custom_delivery_tax. Optional: fields."
      -  },
      -  {
      -    "const": "comments_add",
      -    "description": "Adds a product comment (product id in entry_id or id). Required: message. Optional: entry_id, id, pros, cons, parent_id, user_id, subscribe_to_replies, fields."
      -  },
      -  {
      -    "const": "comments_update",
      -    "description": "Updates a product comment. Required: id. Optional: message, pros, cons, fields."
      -  },
      -  {
      -    "const": "set_currency_rate",
      -    "description": "Sets the rate of a shop currency. Required: curr_code, curr_rate. Optional: fields."
      -  }
      -]New value: +[
      +  {
      +    "const": "category_add",
      +    "description": "Creates a category, with an image when an image slot is filled. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: name. Optional: pid, parent_id, global_cat, dscr, brief, meta_title, meta_dscr, url, pos, view_groups, add_groups, exclude_from_discount, fields, image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path."
      +  },
      +  {
      +    "const": "category_update",
      +    "description": "Updates a category; a filled image slot replaces its image. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). The current image is removed before the new one is saved, so a file with such an extension that is not a valid image leaves the category without an image. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: name, pid, parent_id, global_cat, dscr, brief, meta_title, meta_dscr, url, pos, view_groups, add_groups, exclude_from_discount, fields, image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path."
      +  },
      +  {
      +    "const": "category_show",
      +    "description": "Shows a hidden category. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "category_hide",
      +    "description": "Hides a category. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "category_image",
      +    "description": "Uploads the image of a category from the first filled image slot. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). The current image is removed before the new one is saved, so a file with such an extension that is not a valid image leaves the category without an image. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, fields."
      +  },
      +  {
      +    "const": "add",
      +    "description": "Creates a product. Required: cat_id, name. Optional: brief, dscr, html_dscr, price, price_in, price_old, stock, art, brand, url, meta_title, meta_dscr, tags, type, cats_add, ch_addcat, unit, weight, warr, undisc, fields."
      +  },
      +  {
      +    "const": "update",
      +    "description": "Updates a product. Required: id. Optional: cat_id, name, brief, dscr, html_dscr, price, price_in, price_old, stock, art, brand, url, meta_title, meta_dscr, tags, type, cats_add, ch_addcat, unit, weight, warr, undisc, fields."
      +  },
      +  {
      +    "const": "hide",
      +    "description": "Hides or shows a product. Required: id. Optional: hide, fields."
      +  },
      +  {
      +    "const": "cnt_save",
      +    "description": "Saves product counters (views, sales, orders, rating, stock). Required: id. Optional: views, solds, ordered, rate_num, rate_sum, stock_q, fields."
      +  },
      +  {
      +    "const": "img_add",
      +    "description": "Adds images to a product. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, image_paths, image_upload_ids, image_site_paths, images, file_add_cnt, fields."
      +  },
      +  {
      +    "const": "img_edit",
      +    "description": "Replaces the product image in slot img (0 is the main image; the slot must already hold an image). The new image can keep the URL of the old one. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id, img, confirm. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, fields."
      +  },
      +  {
      +    "const": "variation_update",
      +    "description": "Updates one variation of a product. Required: id, variation_crc. Optional: art, stock, price, price_old, weight, fields."
      +  },
      +  {
      +    "const": "variation_dict_save",
      +    "description": "Creates a variation dictionary (name and values), or updates the dictionary id: a new name and/or the full list of values. Required: id or name. Optional: values, fields."
      +  },
      +  {
      +    "const": "variation_load",
      +    "description": "Loads the variations of a product into its edit form. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "variation_gen",
      +    "description": "Generates product variations from var_* keys in fields. Required: id, confirm. Optional: fields."
      +  },
      +  {
      +    "const": "variation_edit_save",
      +    "description": "Saves product variations from var_* keys in fields. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "stock_genall",
      +    "description": "Generates all option sets of a product stock. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "stock_add",
      +    "description": "Adds an option set to a product stock. Required: id, opt_sel. Optional: fields."
      +  },
      +  {
      +    "const": "stock_save",
      +    "description": "Saves product stock from stock_* keys in fields. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "basket_add",
      +    "description": "Adds a product to the basket. Required: id. Optional: cnt, opt, now, fields."
      +  },
      +  {
      +    "const": "basket_update",
      +    "description": "Changes the quantity of a basket line. Required: id. Optional: cnt, opt, now, fields."
      +  },
      +  {
      +    "const": "checkout_update",
      +    "description": "Recalculates or changes the unfinished order (mode recalc or change; checkout field_N keys in fields). Required: mode. Optional: fields."
      +  },
      +  {
      +    "const": "checkout_submit",
      +    "description": "Places the order from the basket and sends the order notices. No payment is taken: the order waits for payment by the chosen method. Required: confirm. Optional: payment_id, delivery_id, promo_code, custom_delivery_tax, fields."
      +  },
      +  {
      +    "const": "invoice_hide",
      +    "description": "Moves orders to an order group. Required: ids or id. Optional: hide, fields."
      +  },
      +  {
      +    "const": "invoice_courier",
      +    "description": "Assigns a courier to orders. Required: ids or id, group_courier. Optional: fields."
      +  },
      +  {
      +    "const": "invoice_status",
      +    "description": "Sets the status of orders; a paid status is set without any payment. When the shop returns cancelled payments to the balance, moving an order that a registered buyer actually paid online or from the balance from a paid status (2-8) to new, awaiting payment, cancelled or payment processing credits its total to the internal shop balance of the buyer; the buyer gets nothing back for an order that was never paid online or from the balance. Whether a later return to a paid status debits the credited total depends on the status history of the order: it may not be debited, repeated status changes may credit it again, and with some shop settings it may be debited again. Moving an order between the delivered or completed statuses and any other status also credits or debits the internal balances of the user sellers of its goods and the Telegram shop referrer reward, when those are in use, whether or not the order was paid; a move between delivered and completed changes nothing. Required: ids or id, status, confirm. Optional: fields."
      +  },
      +  {
      +    "const": "invoice_payment",
      +    "description": "Changes the payment method of an order that can still be paid (order hash in order or id); no payment is taken. When the new method is set up so, the order also gets the payment processing status, which can credit or debit internal balances as in invoice_status. The reply may carry the order link and the payment form of the new method for the buyer. Required: order or id, payment_id, confirm. Optional: fields."
      +  },
      +  {
      +    "const": "order_update",
      +    "description": "Changes the goods of an order: quantities, options and prices of its lines, or removes lines (keys in fields). The order total is recalculated, and that total is what may later go back to the balance of the buyer on cancellation. The status and note values are not applied: use invoice_status for the status. Required: order. Optional: status, note, fields."
      +  },
      +  {
      +    "const": "order_add_goods",
      +    "description": "Adds goods to an order. Required: order. Optional: fields."
      +  },
      +  {
      +    "const": "order_delivery_tax",
      +    "description": "Sets a custom delivery cost of an order. Required: order, custom_delivery_tax. Optional: fields."
      +  },
      +  {
      +    "const": "comments_add",
      +    "description": "Adds a product comment (product id in entry_id or id). Required: entry_id or id, message. Optional: pros, cons, parent_id, user_id, subscribe_to_replies, fields."
      +  },
      +  {
      +    "const": "comments_update",
      +    "description": "Updates a product comment. Required: id. Optional: message, pros, cons, fields."
      +  },
      +  {
      +    "const": "set_currency_rate",
      +    "description": "Sets the rate of a shop currency. Required: curr_code, curr_rate. Optional: fields."
      +  }
      +]
    • changedInput schema / properties / ids / description
      Previous value: -"Comma-separated ids (invoice_*, stock_remove)."New value: +"Ids separated by commas (invoice_*: order ids, also separated by |; stock_remove)."
  2. Changed4 schema fields changed
    • changedInput schema / properties / action / enum
      Previous value: -[
      -  "category_add",
      -  "category_update",
      -  "category_show",
      -  "category_hide",
      -  "category_image",
      -  "add",
      -  "update",
      -  "hide",
      -  "cnt_save",
      -  "img_add",
      -  "img_edit",
      -  "variation_update",
      -  "variation_dict_save",
      -  "variation_load",
      -  "variation_gen",
      -  "variation_edit_save",
      -  "stock_genall",
      -  "stock_add",
      -  "stock_save",
      -  "basket_add",
      -  "basket_update",
      -  "checkout_update",
      -  "checkout_submit",
      -  "invoice_hide",
      -  "invoice_courier",
      -  "invoice_status",
      -  "invoice_payment",
      -  "order_update",
      -  "order_add_goods",
      -  "order_delivery_tax",
      -  "comments_add",
      -  "comments_update",
      -  "set_currency_rate",
      -  "balance_change",
      -  "balance_set"
      -]New value: +[
      +  "category_add",
      +  "category_update",
      +  "category_show",
      +  "category_hide",
      +  "category_image",
      +  "add",
      +  "update",
      +  "hide",
      +  "cnt_save",
      +  "img_add",
      +  "img_edit",
      +  "variation_update",
      +  "variation_dict_save",
      +  "variation_load",
      +  "variation_gen",
      +  "variation_edit_save",
      +  "stock_genall",
      +  "stock_add",
      +  "stock_save",
      +  "basket_add",
      +  "basket_update",
      +  "checkout_update",
      +  "checkout_submit",
      +  "invoice_hide",
      +  "invoice_courier",
      +  "invoice_status",
      +  "invoice_payment",
      +  "order_update",
      +  "order_add_goods",
      +  "order_delivery_tax",
      +  "comments_add",
      +  "comments_update",
      +  "set_currency_rate"
      +]
    • changedInput schema / properties / action / oneOf
      Previous value: -[
      -  {
      -    "const": "category_add",
      -    "description": "Creates a category, with an image when an image slot is filled. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Optional: name, pid, parent_id, global_cat, dscr, brief, meta_title, meta_dscr, url, pos, view_groups, add_groups, exclude_from_discount, fields, image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path."
      -  },
      -  {
      -    "const": "category_update",
      -    "description": "Updates a category; a filled image slot replaces its image. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). The current image is removed before the new one is saved, so a file with such an extension that is not a valid image leaves the category without an image. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: name, pid, parent_id, global_cat, dscr, brief, meta_title, meta_dscr, url, pos, view_groups, add_groups, exclude_from_discount, fields, image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path."
      -  },
      -  {
      -    "const": "category_show",
      -    "description": "Shows a hidden category. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "category_hide",
      -    "description": "Hides a category. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "category_image",
      -    "description": "Uploads the image of a category from the first filled image slot. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). The current image is removed before the new one is saved, so a file with such an extension that is not a valid image leaves the category without an image. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, fields."
      -  },
      -  {
      -    "const": "add",
      -    "description": "Creates a product. Optional: cat_id, name, brief, dscr, html_dscr, price, price_in, price_old, stock, art, brand, url, meta_title, meta_dscr, tags, type, cats_add, ch_addcat, unit, weight, warr, undisc, fields."
      -  },
      -  {
      -    "const": "update",
      -    "description": "Updates a product. Required: id. Optional: cat_id, name, brief, dscr, html_dscr, price, price_in, price_old, stock, art, brand, url, meta_title, meta_dscr, tags, type, cats_add, ch_addcat, unit, weight, warr, undisc, fields."
      -  },
      -  {
      -    "const": "hide",
      -    "description": "Hides or shows a product. Required: id. Optional: hide, fields."
      -  },
      -  {
      -    "const": "cnt_save",
      -    "description": "Saves product counters (views, sales, orders, rating, stock). Required: id. Optional: views, solds, ordered, rate_num, rate_sum, stock_q, fields."
      -  },
      -  {
      -    "const": "img_add",
      -    "description": "Adds images to a product. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, image_paths, image_upload_ids, image_site_paths, images, file_add_cnt, fields."
      -  },
      -  {
      -    "const": "img_edit",
      -    "description": "Replaces the product image in slot img (0 is the main image; the slot must already hold an image). The new image can keep the URL of the old one. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id, img, confirm. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, fields."
      -  },
      -  {
      -    "const": "variation_update",
      -    "description": "Updates one variation of a product. Required: id, variation_crc. Optional: art, stock, price, price_old, weight, fields."
      -  },
      -  {
      -    "const": "variation_dict_save",
      -    "description": "Creates a variation dictionary (name and values), or updates the dictionary id: a new name and/or the full list of values. Optional: id, name, values, fields."
      -  },
      -  {
      -    "const": "variation_load",
      -    "description": "Loads the variations of a product into its edit form. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "variation_gen",
      -    "description": "Generates product variations from var_* keys in fields. Required: id, confirm. Optional: fields."
      -  },
      -  {
      -    "const": "variation_edit_save",
      -    "description": "Saves product variations from var_* keys in fields. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "stock_genall",
      -    "description": "Generates all option sets of a product stock. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "stock_add",
      -    "description": "Adds an option set to a product stock. Required: id, opt_sel. Optional: fields."
      -  },
      -  {
      -    "const": "stock_save",
      -    "description": "Saves product stock from stock_* keys in fields. Required: id. Optional: fields."
      -  },
      -  {
      -    "const": "basket_add",
      -    "description": "Adds a product to the basket. Required: id. Optional: cnt, opt, now, fields."
      -  },
      -  {
      -    "const": "basket_update",
      -    "description": "Changes the quantity of a basket line. Required: id. Optional: cnt, opt, now, fields."
      -  },
      -  {
      -    "const": "checkout_update",
      -    "description": "Recalculates or changes the unfinished order (mode recalc or change; checkout field_N keys in fields). Required: mode. Optional: fields."
      -  },
      -  {
      -    "const": "checkout_submit",
      -    "description": "Places the order from the basket. Required: confirm. Optional: payment_id, delivery_id, promo_code, custom_delivery_tax, fields."
      -  },
      -  {
      -    "const": "invoice_hide",
      -    "description": "Moves orders to an order group. Optional: ids, id, hide, fields."
      -  },
      -  {
      -    "const": "invoice_courier",
      -    "description": "Assigns a courier to orders. Required: group_courier. Optional: ids, id, fields."
      -  },
      -  {
      -    "const": "invoice_status",
      -    "description": "Sets the status of orders. Required: status. Optional: ids, id, fields."
      -  },
      -  {
      -    "const": "invoice_payment",
      -    "description": "Changes the payment method of an order (order hash in order or id). Required: payment_id. Optional: order, id, fields."
      -  },
      -  {
      -    "const": "order_update",
      -    "description": "Changes the goods, status or note of an order. Required: order. Optional: status, note, fields."
      -  },
      -  {
      -    "const": "order_add_goods",
      -    "description": "Adds goods to an order. Required: order. Optional: fields."
      -  },
      -  {
      -    "const": "order_delivery_tax",
      -    "description": "Sets a custom delivery cost of an order. Required: order, custom_delivery_tax. Optional: fields."
      -  },
      -  {
      -    "const": "comments_add",
      -    "description": "Adds a product comment (product id in entry_id or id). Required: message. Optional: entry_id, id, pros, cons, parent_id, user_id, subscribe_to_replies, fields."
      -  },
      -  {
      -    "const": "comments_update",
      -    "description": "Updates a product comment. Required: id. Optional: message, pros, cons, fields."
      -  },
      -  {
      -    "const": "set_currency_rate",
      -    "description": "Sets the rate of a shop currency. Required: curr_code, curr_rate. Optional: fields."
      -  },
      -  {
      -    "const": "balance_change",
      -    "description": "Changes the balance of a user by amount: a positive amount adds to it, a negative one subtracts. A subtraction larger than the current balance is refused. A note goes in fields.comment. Required: user_id, amount, confirm. Optional: fields."
      -  },
      -  {
      -    "const": "balance_set",
      -    "description": "Sets the balance of a user. Required: user_id, amount, confirm. Optional: fields."
      -  }
      -]New value: +[
      +  {
      +    "const": "category_add",
      +    "description": "Creates a category, with an image when an image slot is filled. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Optional: name, pid, parent_id, global_cat, dscr, brief, meta_title, meta_dscr, url, pos, view_groups, add_groups, exclude_from_discount, fields, image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path."
      +  },
      +  {
      +    "const": "category_update",
      +    "description": "Updates a category; a filled image slot replaces its image. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). The current image is removed before the new one is saved, so a file with such an extension that is not a valid image leaves the category without an image. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: name, pid, parent_id, global_cat, dscr, brief, meta_title, meta_dscr, url, pos, view_groups, add_groups, exclude_from_discount, fields, image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path."
      +  },
      +  {
      +    "const": "category_show",
      +    "description": "Shows a hidden category. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "category_hide",
      +    "description": "Hides a category. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "category_image",
      +    "description": "Uploads the image of a category from the first filled image slot. The category image must be a .jpg, .png or .gif file (.jpeg is renamed to .jpg). The current image is removed before the new one is saved, so a file with such an extension that is not a valid image leaves the category without an image. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, fields."
      +  },
      +  {
      +    "const": "add",
      +    "description": "Creates a product. Optional: cat_id, name, brief, dscr, html_dscr, price, price_in, price_old, stock, art, brand, url, meta_title, meta_dscr, tags, type, cats_add, ch_addcat, unit, weight, warr, undisc, fields."
      +  },
      +  {
      +    "const": "update",
      +    "description": "Updates a product. Required: id. Optional: cat_id, name, brief, dscr, html_dscr, price, price_in, price_old, stock, art, brand, url, meta_title, meta_dscr, tags, type, cats_add, ch_addcat, unit, weight, warr, undisc, fields."
      +  },
      +  {
      +    "const": "hide",
      +    "description": "Hides or shows a product. Required: id. Optional: hide, fields."
      +  },
      +  {
      +    "const": "cnt_save",
      +    "description": "Saves product counters (views, sales, orders, rating, stock). Required: id. Optional: views, solds, ordered, rate_num, rate_sum, stock_q, fields."
      +  },
      +  {
      +    "const": "img_add",
      +    "description": "Adds images to a product. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, image_paths, image_upload_ids, image_site_paths, images, file_add_cnt, fields."
      +  },
      +  {
      +    "const": "img_edit",
      +    "description": "Replaces the product image in slot img (0 is the main image; the slot must already hold an image). The new image can keep the URL of the old one. Image slots take inline bytes (*_base64 with *_filename), an upload_direct id (*_upload_id), a file already on the site (*_site_path), or a path on the MCP server host (*_path, not reachable for remote agents). Required: id, img, confirm. Optional: image_path, image_base64, image_filename, image_upload_id, image_site_path, file_path, file_base64, file_filename, file_upload_id, file_site_path, fields."
      +  },
      +  {
      +    "const": "variation_update",
      +    "description": "Updates one variation of a product. Required: id, variation_crc. Optional: art, stock, price, price_old, weight, fields."
      +  },
      +  {
      +    "const": "variation_dict_save",
      +    "description": "Creates a variation dictionary (name and values), or updates the dictionary id: a new name and/or the full list of values. Optional: id, name, values, fields."
      +  },
      +  {
      +    "const": "variation_load",
      +    "description": "Loads the variations of a product into its edit form. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "variation_gen",
      +    "description": "Generates product variations from var_* keys in fields. Required: id, confirm. Optional: fields."
      +  },
      +  {
      +    "const": "variation_edit_save",
      +    "description": "Saves product variations from var_* keys in fields. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "stock_genall",
      +    "description": "Generates all option sets of a product stock. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "stock_add",
      +    "description": "Adds an option set to a product stock. Required: id, opt_sel. Optional: fields."
      +  },
      +  {
      +    "const": "stock_save",
      +    "description": "Saves product stock from stock_* keys in fields. Required: id. Optional: fields."
      +  },
      +  {
      +    "const": "basket_add",
      +    "description": "Adds a product to the basket. Required: id. Optional: cnt, opt, now, fields."
      +  },
      +  {
      +    "const": "basket_update",
      +    "description": "Changes the quantity of a basket line. Required: id. Optional: cnt, opt, now, fields."
      +  },
      +  {
      +    "const": "checkout_update",
      +    "description": "Recalculates or changes the unfinished order (mode recalc or change; checkout field_N keys in fields). Required: mode. Optional: fields."
      +  },
      +  {
      +    "const": "checkout_submit",
      +    "description": "Places the order from the basket and sends the order notices. No payment is taken: the order waits for payment by the chosen method. Required: confirm. Optional: payment_id, delivery_id, promo_code, custom_delivery_tax, fields."
      +  },
      +  {
      +    "const": "invoice_hide",
      +    "description": "Moves orders to an order group. Optional: ids, id, hide, fields."
      +  },
      +  {
      +    "const": "invoice_courier",
      +    "description": "Assigns a courier to orders. Required: group_courier. Optional: ids, id, fields."
      +  },
      +  {
      +    "const": "invoice_status",
      +    "description": "Sets the status of orders; a paid status is set without any payment. When the shop returns cancelled payments to the balance, moving an order that a registered buyer actually paid online or from the balance from a paid status (2-8) to new, awaiting payment, cancelled or payment processing credits its total to the internal shop balance of the buyer; the buyer gets nothing back for an order that was never paid online or from the balance. Whether a later return to a paid status debits the credited total depends on the status history of the order: it may not be debited, repeated status changes may credit it again, and with some shop settings it may be debited again. Moving an order between the delivered or completed statuses and any other status also credits or debits the internal balances of the user sellers of its goods and the Telegram shop referrer reward, when those are in use, whether or not the order was paid; a move between delivered and completed changes nothing. Required: status, confirm. Optional: ids, id, fields."
      +  },
      +  {
      +    "const": "invoice_payment",
      +    "description": "Changes the payment method of an order that can still be paid (order hash in order or id); no payment is taken. When the new method is set up so, the order also gets the payment processing status, which can credit or debit internal balances as in invoice_status. The reply may carry the order link and the payment form of the new method for the buyer. Required: payment_id, confirm. Optional: order, id, fields."
      +  },
      +  {
      +    "const": "order_update",
      +    "description": "Changes the goods of an order: quantities, options and prices of its lines, or removes lines (keys in fields). The order total is recalculated, and that total is what may later go back to the balance of the buyer on cancellation. The status and note values are not applied: use invoice_status for the status. Required: order. Optional: status, note, fields."
      +  },
      +  {
      +    "const": "order_add_goods",
      +    "description": "Adds goods to an order. Required: order. Optional: fields."
      +  },
      +  {
      +    "const": "order_delivery_tax",
      +    "description": "Sets a custom delivery cost of an order. Required: order, custom_delivery_tax. Optional: fields."
      +  },
      +  {
      +    "const": "comments_add",
      +    "description": "Adds a product comment (product id in entry_id or id). Required: message. Optional: entry_id, id, pros, cons, parent_id, user_id, subscribe_to_replies, fields."
      +  },
      +  {
      +    "const": "comments_update",
      +    "description": "Updates a product comment. Required: id. Optional: message, pros, cons, fields."
      +  },
      +  {
      +    "const": "set_currency_rate",
      +    "description": "Sets the rate of a shop currency. Required: curr_code, curr_rate. Optional: fields."
      +  }
      +]
    • removedInput schema / properties / amount
      Removed value: -{
      -  "description": "balance_change: signed change, non-zero. balance_set: the new balance, zero or more.",
      -  "type": [
      -    "number",
      -    "string"
      -  ]
      -}
    • changedInput schema / properties / confirm / description
      Previous value: -"Pass true only after the user approves this change. Required by: img_edit, variation_gen, checkout_submit, balance_change, balance_set."New value: +"Pass true only after the user approves this change. Required by: img_edit, variation_gen, checkout_submit, invoice_status, invoice_payment."
  3. Added

TDQS

A3.5/5.0
Behavior4/5

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

Annotations already declare readOnly=false, destructive=true, and openWorld=true. The description adds important domain-specific behavior: no action takes or sends money, payment-method changes may set processing status, order status changes may credit or debit internal shop balances, and no action directly sets a balance. It could also mention confirmation requirements for destructive actions, but that detail is covered in the schema.

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

Conciseness4/5

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

The description is front-loaded with purpose and limited to two sentences with no filler. The second sentence is dense and lengthy, but it carries necessary financial caveats for a destructive shop-write tool.

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

Completeness4/5

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

Given the rich action schema and annotations, the description supplies the high-level scope and critical financial/balance side effects that would otherwise be missed. It omits explicit routing to shop_read/shop_delete and confirmation guidance, but the schema covers action-specific details and the sibling names provide strong context.

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

Parameters2/5

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

The description gives no parameter-level meaning beyond listing the shop areas affected. With 80 parameters and only 64% schema description coverage, many arguments rely entirely on schema text, and the description does not compensate for undocumented parameters or explain how action-specific parameters are selected.

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

Purpose4/5

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

The description uses clear write verbs ('Creates and updates') and enumerates the shop domains covered: categories, products, images, variations, stock, basket, checkout, orders, comments, and currency rates. It is clearly a broad write tool, but it does not explicitly distinguish itself from siblings like shop_read or shop_delete.

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

Usage Guidelines3/5

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

The opening 'Creates and updates...' implies this tool is for write/edit operations, and the payment caveat clarifies that it does not process real money. However, it never says when to use this versus shop_read for reads or shop_delete for deletions, nor does it flag when to avoid it.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.