Skip to main content
Glama
@cmssy/mcp-server

@cmssy/mcp-server

Official

List orders

list_orders
Read-only

Retrieve and filter workspace orders by payment, fulfillment, delivery or warehouse status, customer, company, currency, and date range, with cursor-based pagination for large result sets.

Instructions

List orders in the workspace. Filter by payment, fulfillment or delivery status, state (open/closed/canceled), customer, company (B2B), pipeline stage, warehouse queue (to pack, in transit, shipping problem, returns), a search string (customer email or company name), currency, or a date range. Each order carries customerId, companyId and companyName when it was placed for a customer or a company. Paginated: while hasMore is true, pass nextCursor back as cursor while it is set; if hasMore is true but nextCursor is null, page with the offset instead, and past offset 10000 narrow the filter.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_orders"
  }
}

Input Schema

NameRequiredDescriptionDefault
skipNoHow many orders to skip, at most 10000 - the paging offset (there is no offset parameter); page past that with cursor
limitNoPage size, at most 100; pass nextCursor back as cursor while it is set
queueNoA warehouse work queue, the same tabs as the admin order list: to_pack = open, paid and not yet fully shipped; in_transit = a parcel has a label or is on its way, without a delivery problem; shipping_problem = delivery status exception; returns = an open return. Combines with every other filter.
stateNoopen, closed (done) or canceled
cursorNonextCursor from the previous page. The page continues after it in the same filter and sort; leave the skip/offset at 0 when you pass it
dateToNoISO date-time upper bound
searchNoCase-insensitive contains match on the customer email or the frozen company name
currencyNoOnly orders placed in this currency (ISO 4217, e.g. EUR) - order totals are never added across currencies, so filter by it before summing
dateFromNoISO date-time lower bound
companyIdNoOnly orders placed for this company record (B2B). Pass the company record's id - find it with list_records on the company model named by the account model's auth.companyField; a company name goes into search instead.
customerIdNo
paymentStatusNo
deliveryStatusNo
pipelineStageIdNo
fulfillmentStatusNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.146.2
    • addedInput schema / properties / cursor
      Added value: +{
      +  "description": "nextCursor from the previous page. The page continues after it in the same filter and sort; leave the skip/offset at 0 when you pass it",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • changedInput schema / properties / limit / description
      Previous value: -"Page size, at most 100; page on with skip while hasMore is true"New value: +"Page size, at most 100; pass nextCursor back as cursor while it is set"
    • changedInput schema / properties / skip / description
      Previous value: -"How many orders to skip - the paging offset (there is no offset parameter)"New value: +"How many orders to skip, at most 10000 - the paging offset (there is no offset parameter); page past that with cursor"
    • changedInput schema / properties / skip / maximum
      Previous value: -9007199254740991New value: +10000
  2. Changed15 schema fields changedv0.73.2
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / companyId
      Added value: +{
      +  "description": "Only orders placed for this company record (B2B). Pass the company record's id - find it with list_records on the company model named by the account model's auth.companyField; a company name goes into search instead.",
      +  "type": "string"
      +}
    • addedInput schema / properties / currency
      Added value: +{
      +  "description": "Only orders placed in this currency (ISO 4217, e.g. EUR) - order totals are never added across currencies, so filter by it before summing",
      +  "pattern": "^[A-Z]{3}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / deliveryStatus
      Added value: +{
      +  "enum": [
      +    "none",
      +    "in_transit",
      +    "partially_delivered",
      +    "delivered",
      +    "exception"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / fulfillmentStatus / enum
      Previous value: -[
      -  "unfulfilled",
      -  "partially_fulfilled",
      -  "fulfilled",
      -  "returned"
      -]New value: +[
      +  "unfulfilled",
      +  "partially_fulfilled",
      +  "fulfilled",
      +  "not_required"
      +]
    • removedInput schema / properties / limit / default
      Removed value: -20
    • addedInput schema / properties / limit / description
      Added value: +"Page size, at most 100; page on with skip while hasMore is true"
    • changedInput schema / properties / limit / maximum
      Previous value: -9007199254740991New value: +100
    • changedInput schema / properties / limit / minimum
      Previous value: --9007199254740991New value: +1
    • addedInput schema / properties / queue
      Added value: +{
      +  "description": "A warehouse work queue, the same tabs as the admin order list: to_pack = open, paid and not yet fully shipped; in_transit = a parcel has a label or is on its way, without a delivery problem; shipping_problem = delivery status exception; returns = an open return. Combines with every other filter.",
      +  "enum": [
      +    "to_pack",
      +    "in_transit",
      +    "shipping_problem",
      +    "returns"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / search / description
      Added value: +"Case-insensitive contains match on the customer email or the frozen company name"
    • removedInput schema / properties / skip / default
      Removed value: -0
    • addedInput schema / properties / skip / description
      Added value: +"How many orders to skip - the paging offset (there is no offset parameter)"
    • changedInput schema / properties / skip / minimum
      Previous value: --9007199254740991New value: +0
    • addedInput schema / properties / state
      Added value: +{
      +  "description": "open, closed (done) or canceled",
      +  "enum": [
      +    "open",
      +    "closed",
      +    "canceled"
      +  ],
      +  "type": "string"
      +}
  3. First observedv0.73.1

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare this a safe read (readOnlyHint true, destructiveHint false), and the description adds behavior those annotations cannot convey: the cursor/offset paging protocol, the 10000 offset ceiling, and the warning that order totals are never added across currencies so results must be filtered by currency before summing. It also discloses that companyId/companyName are frozen at order time. Sort order and total counts remain undocumented.

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: scope plus filter inventory first, then entity linkage, then paging. The paging sentence is long and its phrasing ("pass nextCursor back as cursor while it is set") is slightly convoluted, and it partially restates the limit/skip schema descriptions, but the hasMore-null fallback rule is not available anywhere else, so the sentence earns its place.

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?

For a 15-parameter, read-only listing tool with no output schema, the description covers scope, filter semantics, entity linkage fields returned on each order, and the full paging protocol. Gaps are minor: default sort order, whether any aggregate/total is returned, and the meaning of the undocumented id parameters are not stated.

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

Parameters3/5

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

With 67% schema coverage the schema already carries a lot, but the description still adds real meaning: search matches customer email or company name, companyId must be a record id rather than a name, and currency must be filtered before any sum. Five of the fifteen parameters (customerId, pipelineStageId, paymentStatus, deliveryStatus, fulfillmentStatus) are undocumented in both schema and description, so it does not fully compensate.

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 and resource ("List orders in the workspace") and immediately enumerates the filterable dimensions (payment/fulfillment/delivery status, state, customer, company, pipeline stage, warehouse queue, search, currency, date range), which lets an agent distinguish it from list_carts, list_customers, and other list_* siblings. It stops short of explicitly naming a sibling as the wrong choice, so it does not reach a 5.

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 routing guidance: use list_records on the company model named by auth.companyField to obtain a companyId, and send a company name to search instead. The pagination instructions also tell the agent exactly how to proceed across pages, including the hasMore-with-null-nextCursor fallback and narrowing filters past offset 10000. No explicit when-not-to-use-this-tool statement, but the context is clear.

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