Search Singapore skincare and beauty, build guest carts, and prepare buyer checkout links.
Scored across 10 tools
Most tools target a distinct resource+action (search, get_product, create/get cart, quote, set item/coupon, get_order). The main overlap is checkout_session vs create_checkout, which both produce a Tanatasa review link and both require idempotency keys; descriptions do differentiate them (feed item IDs vs a quoted cart), so an agent can disambiguate with care but the names invite misselection.
Nine of ten tools follow a clear verb_noun pattern (create_cart, get_cart, quote_cart, set_cart_item, search_products). checkout_session is the lone noun-only outlier, which is a minor but noticeable break in the pattern.
Ten tools is well-scoped for a guest shopping and checkout flow, with each tool mapping to a needed step (discover, inspect, cart, price, checkout, order status). Nothing appears redundant enough to be dropped beyond the checkout overlap.
The surface covers the full browse-to-order lifecycle: search, product detail, cart CRUD for items and coupons, quoting, checkout, and post-purchase status. Gaps are minor — no order history/list, cancellation, or refund path, and no way to clear an abandoned cart explicitly.
Prepare checkout from product feed item IDs and quantities without account login. For guests, call create_cart first and supply its guest_token. Optional item metadata is not authoritative. Returns a Tanatasa review link; the buyer enters delivery details and approves payment. Supply a new idempotency_key per purchase and retain it and guest_token on retries.
| Name | Required | Description | Default |
|---|---|---|---|
| guest_token | No | Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed. | |
| idempotency_key | No | ||
| checkout_session | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing the post-call flow (returns a Tanatasa review link, buyer enters delivery details and approves payment) and the retry contract (new idempotency_key per purchase, retain key and guest_token on retries). Annotations only give generic hints, so this added context is genuinely valuable; what's missing is any statement of failure modes or what happens to a partially-abandoned session.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five tight sentences, front-loaded with the core action, then prerequisites, then the outcome, then retry semantics. Dense but every sentence carries information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description correctly explains what comes back (a review link, with buyer-side completion) and it covers the nested items structure and retry requirements. Minor gaps remain around item id format and session expiry, but an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%—idempotency_key and the whole nested checkout_session object are undocumented in-schema—so the description has to compensate, and it does: it clarifies that items are product feed IDs and quantities, that optional item metadata (name/price/url/description) is not authoritative, and how idempotency_key is used. It still says nothing about the id format or quantity bounds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Prepare checkout from product feed item IDs and quantities') plus the notable constraint that no account login is needed. It does not distinguish itself from the equally-named sibling create_checkout, so an agent still has to infer which checkout entry point to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly gives the guest path: call create_cart first and supply its guest_token. That is real when-to-use guidance with a prerequisite, but it never says when to prefer this over create_checkout or the cart tools (get_cart, quote_cart).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an empty persistent cart without account login. Save cart_id, version and the private guest_token if returned. Pass guest_token on subsequent shopping calls. Account authentication is optional.
| Name | Required | Description | Default |
|---|---|---|---|
| guest_token | No | Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-readonly, non-idempotent, non-destructive, open-world. The description adds genuinely new behavior: the cart is empty at creation, no login is required, and the guest_token is private and must be retained for later cart/checkout calls. That is useful workflow context beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the action and scope, followed by the retention/usage instructions. No filler and nothing redundant with the annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing what comes back and does so (cart_id, version, guest_token). Combined with annotations covering the safety profile and a fully documented single parameter, an agent has everything needed to call it and use the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds downstream meaning for guest_token (retain it and pass it on later shopping calls) rather than just restating the type. The only weakness is that it frames guest_token primarily as something to 'save' from the response, which slightly blurs its role as an optional input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create an empty persistent cart') plus the key scope qualifier 'without account login', which separates it from create_checkout and get_cart. It does not name a sibling explicitly, so an agent must infer the boundary from the guest-vs-account distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear operational context: create first, then pass guest_token on subsequent shopping calls, with account authentication optional. It does not explicitly say when to prefer create_cart over create_checkout, but the guest/no-login framing makes the choice reasonably evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prepare a Tanatasa checkout review link for a quoted cart. Provide quoted version and expected_total in SGD cents. Keep the same idempotency_key and input on retries. Locks cart. Buyer reviews items and enters contact/delivery details on Tanatasa before paying. No payment occurs in this tool; get_order reports progress and webhook-confirmed status.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| version | Yes | ||
| guest_token | No | Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed. | |
| expected_total | Yes | ||
| idempotency_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations covering readOnly=false, openWorld=true, idempotent=true, and destructive=false, the description adds meaningful context: it locks the cart, does not take payment, hands the buyer to Tanatasa for review and details, and requires the same idempotency key on retries. It adds strong behavioral detail without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and tightly written. Each sentence adds operational value: the action, required monetary/version context, retry behavior, cart locking, buyer flow, and non-payment clarification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating checkout-preparation tool with no output schema, the description is largely complete: it covers locking, no-payment behavior, buyer review flow, retry semantics, and status-check routing. It could go slightly further by describing the returned review link or authorization expectations, but the essential call context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 20%, so the description carries most of the burden. It explains the quoted version, expected_total in SGD cents, idempotency_key reuse on retries, and quoted cart context, leaving only guest_token to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Prepare a Tanatasa checkout review link for a quoted cart.' It clearly distinguishes the action from payment and points to get_order for status, though it does not explicitly contrast with the sibling checkout_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'for a quoted cart' and the retry guidance, and it notes that get_order reports progress rather than this tool. However, it does not explicitly say when to choose this over checkout_session or other checkout-adjacent siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read cart items, coupon, version and checkout lock.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| guest_token | No | Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing that the response includes cart version and checkout lock state — data an agent needs for optimistic concurrency — but says nothing about error behavior for stale or locked carts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; every word names a returned artifact. It is terse to the point of omitting routing context, but there is no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, listing the returned fields is helpful, and annotations cover safety. However, for a 2-parameter read on a multi-step cart flow (create_cart → set_cart_item → quote_cart → checkout), it omits how cart_id is obtained and when a guest_token is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%: guest_token is richly documented in the schema, but cart_id has no description anywhere. The description mentions no parameters at all, so it fails to compensate for the undocumented required identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb (Read) and resource (cart) and enumerates the fields returned: items, coupon, version and checkout lock. It does not distinguish itself from siblings like quote_cart or checkout_session, so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No statement of when to call this versus quote_cart (totals) or checkout_session (lock lifecycle), and no mention of prerequisites such as the cart needing to exist. Usage is only implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get payment and fulfilment status and tracking for a purchase created by this guest session or account connection. Supply guest_token for guest purchases. Payment confirmation comes from Stripe webhooks. Does not update prior purchases.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | ||
| guest_token | No | Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful context beyond the annotations: payment status is driven by Stripe webhooks, guest_token is needed for guest purchases, and the tool does not update prior purchases. It stops short of explaining latency or return shape, but it meaningfully supplements the structured safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three compact sentences, front-loaded with the core purpose and followed by the two operationally relevant caveats. Every sentence carries useful information, and none are redundant with the annotations or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, two-parameter status tool with annotations present and no output schema, the description covers the essential context: what status is returned, the guest-token requirement, the webhook dependency, and the no-update behavior. It could be more complete if it described the returned status/tracking fields, but an agent has enough information to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: guest_token has a full schema description, while order_id is undocumented in the schema. The description adds the guest-only condition for guest_token but says nothing about order_id, so it partially compensates for the coverage gap without fully covering both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: getting payment, fulfilment, and tracking status for a purchase. It scopes the resource to purchases created by the guest session or account connection, which implicitly separates it from cart-oriented siblings, but it does not explicitly name an alternative tool or draw a direct boundary with get_cart or checkout_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives one conditional parameter instruction ('Supply guest_token for guest purchases') and notes that payment confirmation comes from Stripe webhooks, but it does not explain when to use this tool versus alternatives such as get_cart or checkout_session. There is no explicit when-not guidance, leaving the agent to infer the workflow position.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get product descriptions, ingredients, usage, images and variants. product accepts a product ID, product slug, variant slug or SKU.
| Name | Required | Description | Default |
|---|---|---|---|
| product | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context by listing the kind of product data returned and the identifier types accepted, though it omits failure modes or lookup ambiguity handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the return content and followed by the critical parameter semantics. No wasted words, and the most important usage detail is stated directly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter lookup tool with no output schema but rich annotations, the description is mostly complete: it explains what data comes back and how to address a product. It lacks only explicit alternative-routing guidance and not-found behavior, which are minor for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden for the single required parameter. It does this well by explaining that product accepts a product ID, product slug, variant slug, or SKU, which is essential information absent from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: get product, and enumerates what is returned (descriptions, ingredients, usage, images, variants). It is clear against generic siblings but does not explicitly distinguish itself from search_products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the accepted identifier forms: use this when you already have a product ID, slug, variant slug, or SKU. However, it never explicitly says when to use this instead of search_products, nor does it state exclusions or error behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reprice the cart with current stock, scheduled prices and discounts. All amounts are SGD cents; shipping is free within Singapore. Stock is not reserved. Save version and total for checkout.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| guest_token | No | Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description goes further by disclosing that amounts are in SGD cents, shipping is free within Singapore, and stock is not reserved during the quote. The only soft tension is 'Save version and total', which implies persistence despite readOnlyHint=true, though quoting typically does pin a version and it is not a clear contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action, then unit/shipping semantics, then the side effect. Every sentence carries information an agent would otherwise have to guess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should say what the quote returns; 'save version and total' hints at a version and a total but says nothing about line items, applied discounts, or per-item pricing. Combined with the undocumented cart_id, this leaves the agent short of what it needs to use the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%: guest_token is well documented in the schema, but the required cart_id has no description anywhere. The description says nothing about either parameter, so it does not compensate for the undocumented required identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Reprice' plus the resource 'cart' is specific, and the phrase 'with current stock, scheduled prices and discounts' tells the agent exactly which inputs feed the computation. It implicitly separates itself from get_cart (a plain read) but never names a sibling or states the boundary explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Save version and total for checkout' implies this is the pricing step that precedes checkout, which is useful workflow context. However, there is no explicit statement of when to call it versus get_cart, and no mention of prerequisites such as needing items in the cart or a valid guest_token.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search public sellable variants by words, brand/category/purpose, skin type, ingredient, availability and price in SGD cents. Use variant_id when adding items; follow next_page for more results.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| page | No | ||
| brand | No | ||
| limit | No | ||
| purpose | No | ||
| category | No | ||
| in_stock | No | ||
| max_price | No | ||
| min_price | No | ||
| skin_type | No | ||
| ingredient | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful context beyond annotations: results are "public sellable variants," prices are in "SGD cents," and pagination uses "next_page." It does not describe the response structure, but with no output schema and rich annotations this is still a solid level of disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted wording. The core search capability is front-loaded, followed by concise operational guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with 11 optional filters and no output schema, the description covers the key facets and pagination behavior. It is nearly complete, though it could better explain how page and limit interact and what fields are returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 parameter meaning. It maps most filters to concepts: words, brand, category, purpose, skin type, ingredient, availability, and price. It clarifies the price unit as SGD cents but does not explain page/limit or q semantics in detail, leaving gaps for an 11-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Search public sellable variants." It also enumerates the searchable facets, making the tool's scope clear. It does not explicitly differentiate from sibling get_product, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives useful follow-up guidance: "Use variant_id when adding items" and "follow next_page for more results." However, it does not say when to use this search tool versus get_product or other sibling tools, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a coupon code or null to remove it. Supply current cart version. Auto discounts also apply.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| version | Yes | ||
| coupon_code | Yes | ||
| guest_token | No | Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, openWorldHint=true and idempotentHint=false, so the description doesn't need to establish that this is a mutating call. It adds some value by noting that auto discounts also apply, hinting at interactions, but it doesn't say what gets destroyed (e.g. whether an existing coupon is silently replaced) or what happens on a stale version.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the action, then the required version, then the discount interaction. No filler and nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent mutation with no output schema, the agent still lacks key facts: whether applying a coupon replaces an existing one, what the version-mismatch failure looks like, and whether auto discounts are recomputed or overridden. Adequate but with real gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25%, so the description must compensate—and it does for the two non-obvious parameters: coupon_code accepts null to remove a coupon, and version must be the current cart version. Only cart_id and the guest token convention are left to the schema, which handles guest_token adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('apply a coupon code') and covers the removal case via null, which distinguishes it from the sibling set_cart_item. It's clear what the tool does, though it doesn't explicitly name how it differs from other cart-mutating siblings like set_cart_item beyond the resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Apply a coupon code or null to remove it' implies when to use the tool and how to undo, but there is no explicit guidance on when to prefer this versus other cart tools, nor on prerequisites such as needing an owned cart or guest session. Usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add or update a variant using an absolute quantity; zero removes it. Supply the current cart version. Maximum 20 variants and 99 units each; availability is checked.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| version | Yes | ||
| quantity | Yes | ||
| variant_id | Yes | ||
| guest_token | No | Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the description's real contribution is the absolute-quantity semantics, the zero-removes behavior, the optimistic-concurrency requirement via version, and the availability check. These are meaningful behavioral facts beyond the structured data. It stops short of saying what a stale-version response looks like or whether removal is permanent, which keeps it at 4 rather than 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short clauses, each carrying distinct information: the operation, the zero-removal edge case, the concurrency prerequisite, and the limits. Front-loaded and zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with annotations covering the safety profile and no output schema, the description covers the operational constraints an agent needs (absolute semantics, zero removal, version, caps, availability). Minor gaps: no mention that guest checkout requires guest_token in this call, and no statement about failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (guest_token only), so the description carries real burden. It compensates well for version ('current cart version') and quantity (absolute, zero removes, 99 cap), but says nothing about cart_id or variant_id format/source, leaving two required parameters to inference from their names and formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Add or update a variant') with the crucial qualifier that quantity is absolute rather than incremental, which distinguishes it from a generic line-item mutation. It doesn't name any sibling (get_cart, set_cart_coupon, checkout_session) explicitly, but the resource is specific enough that confusion is unlikely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'zero removes it' is a genuinely useful usage rule, and 'Supply the current cart version' tells the agent a prerequisite. However, there is no guidance on when to prefer this over siblings, nor on what happens on a version conflict beyond the implication that the version must match.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
checkout_session1 field changedInput schema / properties / guest_tokenAdded value: +{
+ "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
+ "pattern": "^[a-f0-9]{64}$",
+ "type": "string"
+}create_cart1 field changedInput schema / properties / guest_tokenAdded value: +{
+ "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
+ "pattern": "^[a-f0-9]{64}$",
+ "type": "string"
+}create_checkout1 field changedInput schema / properties / guest_tokenAdded value: +{
+ "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
+ "pattern": "^[a-f0-9]{64}$",
+ "type": "string"
+}get_cart1 field changedInput schema / properties / guest_tokenAdded value: +{
+ "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
+ "pattern": "^[a-f0-9]{64}$",
+ "type": "string"
+}get_order1 field changedInput schema / properties / guest_tokenAdded value: +{
+ "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
+ "pattern": "^[a-f0-9]{64}$",
+ "type": "string"
+}quote_cart1 field changedInput schema / properties / guest_tokenAdded value: +{
+ "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
+ "pattern": "^[a-f0-9]{64}$",
+ "type": "string"
+}set_cart_coupon1 field changedInput schema / properties / guest_tokenAdded value: +{
+ "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
+ "pattern": "^[a-f0-9]{64}$",
+ "type": "string"
+}set_cart_item1 field changedInput schema / properties / guest_tokenAdded value: +{
+ "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
+ "pattern": "^[a-f0-9]{64}$",
+ "type": "string"
+}checkout_session1 field changedInput schema / properties / guest_tokenRemoved value: -{
- "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
- "pattern": "^[a-f0-9]{64}$",
- "type": "string"
-}create_cart1 field changedInput schema / properties / guest_tokenRemoved value: -{
- "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
- "pattern": "^[a-f0-9]{64}$",
- "type": "string"
-}create_checkout1 field changedInput schema / properties / guest_tokenRemoved value: -{
- "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
- "pattern": "^[a-f0-9]{64}$",
- "type": "string"
-}get_cart1 field changedInput schema / properties / guest_tokenRemoved value: -{
- "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
- "pattern": "^[a-f0-9]{64}$",
- "type": "string"
-}get_order1 field changedInput schema / properties / guest_tokenRemoved value: -{
- "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
- "pattern": "^[a-f0-9]{64}$",
- "type": "string"
-}quote_cart1 field changedInput schema / properties / guest_tokenRemoved value: -{
- "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
- "pattern": "^[a-f0-9]{64}$",
- "type": "string"
-}set_cart_coupon1 field changedInput schema / properties / guest_tokenRemoved value: -{
- "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
- "pattern": "^[a-f0-9]{64}$",
- "type": "string"
-}set_cart_item1 field changedInput schema / properties / guest_tokenRemoved value: -{
- "description": "Private guest session token from create_cart. Retain for cart, checkout and purchase-status calls; no account login needed.",
- "pattern": "^[a-f0-9]{64}$",
- "type": "string"
-}checkout_sessioncreate_cartcreate_checkoutget_cartget_orderget_productquote_cartsearch_productsset_cart_couponset_cart_itemSearch ProtoClinical's current K-beauty catalog and manage buyer-approved carts and checkouts.
AI-powered commerce API for luxury skincare shopping. Enables AI agents to search products, browse collections, manage shopping carts, and generate checkout URLs for the Regenique Elegance Shopify store.
Agent-native commerce for SEA/China/global. 43 brands. 6 tools. 9-language search.
AI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
Add one secure layer between your agents and this server.
