hktvmall-mcp

Set basket quantities

hktv_update_cart

Idempotent

Set exact quantities for basket lines (0 removes), up to 25 changes per call, and report the outcomes actually applied by HKTVmall without adding on top.

Instructions

Set exact quantities for basket lines (quantity 0 removes; never adds on top). Up to 25 changes in one call. Each change's outcome (applied, adjusted, rejected with a reason) is read back from HKTVmall: report those, not what you asked for. Lines you do not name are left alone. Over 15 of one item or HK$1,500 added in one call it changes nothing and returns requires_buyer_review. Cannot place or pay for an order. In people mode, account_context must match the current caller, selected account, sharing grant and reconnect epoch; a stale or missing context applies no changes. Needs the account's sign-in.

Input Schema

Name	Required	Description
`changes`	Yes	Exact quantities to set
`confirmed`	No	True only after the person agreed to a change over the caps
`account_context`	No	People mode: account_context from the latest hktv_get_cart

Output Schema

Name	Required	Description	Default
`basket`	Yes
`status`	Yes
`changes`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.15.4Oct 31, 2026

addedInput schema / properties / account_context

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 64,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "People mode: account_context from the latest hktv_get_cart"
+}

First observedv0.12.11Oct 23, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well past the annotations: discloses the purchase caps that trigger requires_buyer_review, that unnamed lines are untouched, that each change's actual outcome (applied/adjusted/rejected) must be read back rather than assumed, that no changes apply with stale account context, and that sign-in is required. These are exactly the failure modes an agent would otherwise hit silently, and nothing contradicts idempotentHint/destructiveHint=false.

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?

Front-loaded with the verb and the removal/no-add rule, then layers caps, context rules, and exclusions in descending importance. It is dense and slightly long, but nearly every clause carries operational information; only the final 'Needs the account's sign-in' is marginally redundant with the account_context sentence.

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?

Covers everything an agent needs for a mutating, open-world commerce call: mutation semantics, caps and review escalation path, outcome-reading obligation, concurrency/precondition requirements via account_context, and the hard limit that it cannot place or pay for an order. With an output schema present, the description correctly spends its length on behavior rather than return values.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains what confirmed gates (a change over the caps, after buyer agreement) and expands account_context into the specific validations it must satisfy — caller, selected account, sharing grant, reconnect epoch. The 25-change ceiling and per-call cap behavior are also restated in operational terms rather than as bare constraints.

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?

States a specific verb and resource ('Set exact quantities for basket lines') and immediately pins the semantics ('quantity 0 removes; never adds on top'), which separates it from any add/increment operation and from the read-only hktv_get_cart sibling. It also bounds scope with 'Cannot place or pay for an order', so an agent knows exactly what class of operation this is.

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?

Gives clear operating context: the 15-per-item / HK$1,500 cap, the requires_buyer_review outcome, and the requirement that confirmed only be set after the person agrees. It does not explicitly name a sibling alternative for the 'just add one item' case, so routing guidance is strong but not exhaustive.

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

Deploy Server