Skip to main content
Glama
@cmssy/mcp-server

@cmssy/mcp-server

Official

Create manual order

create_manual_order

Create a manual admin-entered order with product or ad-hoc line items, set currency and optional shipping address, and use an idempotency key to safely retry unclear calls.

Instructions

Create a manual (admin-entered) order. Each item references a product recordId or is an ad-hoc line with name+price (minor units of the order's currency). currency picks the order's currency (default currency when omitted); payments and refunds on the order are in that currency. shippingAddress is optional; for a customer of a company with a verified VAT id its country decides whether the order is reverse charge, and the order freezes that tax treatment (get_order taxTreatment). Pass an idempotencyKey and, if the call times out or fails unclearly, retry with the same idempotencyKey so the retry cannot create a second order.

Tool call template

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "customerEmail": "<customerEmail>",
      "items": "<items>"
    },
    "name": "create_manual_order"
  }
}

Input Schema

NameRequiredDescriptionDefault
itemsYes
currencyNoThe order's currency: omit for the default currency, or one of the workspace's additional currencies. Product lines are priced in it - a product with no price in it is refused (NO_PRICE_IN_CURRENCY) - and ad-hoc line prices are minor units of it
customerIdNo
customerEmailYesCustomer email for the order
idempotencyKeyNoYour own unique value for this order (e.g. a UUID you generate), up to 128 characters. If the call times out or its result is unclear, retry with the same idempotencyKey: the repeat returns the order the first call created instead of creating a second one, and ignores the repeat's other input. Use a new value for a different order. Omit it and every call creates.
shippingAddressNoDelivery address. Its country decides reverse charge for a buyer whose company has a verified VAT id

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.147.0
    • addedInput schema / properties / idempotencyKey
      Added value: +{
      +  "description": "Your own unique value for this order (e.g. a UUID you generate), up to 128 characters. If the call times out or its result is unclear, retry with the same idempotencyKey: the repeat returns the order the first call created instead of creating a second one, and ignores the repeat's other input. Use a new value for a different order. Omit it and every call creates.",
      +  "maxLength": 128,
      +  "type": "string"
      +}
  2. Changed5 schema fields changedv0.73.2
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / currency
      Added value: +{
      +  "description": "The order's currency: omit for the default currency, or one of the workspace's additional currencies. Product lines are priced in it - a product with no price in it is refused (NO_PRICE_IN_CURRENCY) - and ad-hoc line prices are minor units of it",
      +  "pattern": "^[A-Z]{3}$",
      +  "type": "string"
      +}
    • changedInput schema / properties / items / items / properties / price / description
      Previous value: -"Custom unit price in minor units (ad-hoc item)"New value: +"Custom unit price in minor units of the order's currency (ad-hoc item)"
    • addedInput schema / properties / shippingAddress
      Added value: +{
      +  "description": "Delivery address. Its country decides reverse charge for a buyer whose company has a verified VAT id",
      +  "properties": {
      +    "city": {
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "company": {
      +      "type": "string"
      +    },
      +    "country": {
      +      "description": "ISO 3166-1 alpha-2 country code",
      +      "maxLength": 2,
      +      "minLength": 2,
      +      "type": "string"
      +    },
      +    "line1": {
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "line2": {
      +      "type": "string"
      +    },
      +    "name": {
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "phone": {
      +      "type": "string"
      +    },
      +    "postalCode": {
      +      "minLength": 1,
      +      "type": "string"
      +    },
      +    "region": {
      +      "type": "string"
      +    },
      +    "vatId": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "name",
      +    "line1",
      +    "postalCode",
      +    "city",
      +    "country"
      +  ],
      +  "type": "object"
      +}
    • addedInput schema / required
      Added value: +[
      +  "customerEmail",
      +  "items"
      +]
  3. First observedv0.73.1

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses real behavioral consequences: currency governs pricing and ad-hoc minor units, a product lacking a price in that currency is refused with NO_PRICE_IN_CURRENCY, and the order freezes the reverse-charge tax treatment decided by the address country. The idempotency contract (repeat returns the original order, ignores other input) is spelled out precisely.

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?

Three front-loaded sentences with the core operation first, then currency/tax semantics, then the retry contract. Dense but no filler; the long middle sentence packs several distinct behaviors that could be split for scanability.

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?

Covers the consequential behaviors for a 6-parameter, nested-object mutation with no output schema, and points to get_order taxTreatment for verification afterwards. It doesn't indicate what the success response contains (e.g. the created order id), which leaves a small gap.

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

Parameters5/5

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

Adds meaning the schema doesn't fully carry: the default-currency behavior when currency is omitted, that ad-hoc price is in minor units of the order currency, and that shippingAddress country drives reverse charge only for a company with a verified VAT id. The idempotencyKey prose largely restates the schema but is reinforced with operational context.

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?

Opens with a specific verb+resource, 'Create a manual (admin-entered) order', and the parenthetical scopes it away from customer-facing or imported orders. It doesn't name a sibling alternative, but the operation is unambiguous.

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 concrete use guidance for the retry path ('if the call times out or fails unclearly, retry with the same idempotencyKey') and states that shippingAddress is optional. It stops short of naming when to prefer a different tool, e.g. edit_order or create_record for related work.

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

Deploy Server

Other Tools