Skip to main content
Glama
@cmssy/mcp-server

@cmssy/mcp-server

Official

Create return

create_return

Open an approved return on an order for items a customer is sending back without moving money or stock; restocking and refunds are handled separately.

Instructions

Open a return on an order for items the customer is sending back. A return opened by the merchant starts approved. It does not move money or stock: receive_return restocks, refund_return records the refund. Pass an idempotencyKey and, if the call times out or fails unclearly, retry with the same idempotencyKey so the retry cannot open a second return on the 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": {
      "orderId": "<orderId>",
      "lines": "<lines>"
    },
    "name": "create_return"
  }
}

Input Schema

NameRequiredDescriptionDefault
noteNo
linesYesLines and quantities coming back; only units already handed to the carrier or the customer
carrierNoCarrier of the return parcel
orderIdYes
idempotencyKeyNoYour own unique value for this return (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 return the first call created instead of creating a second one, and ignores the repeat's other input. Use a new value for a different return. Omit it and every call creates.
trackingNumberNoTracking number of the return parcel

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 return (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 return the first call created instead of creating a second one, and ignores the repeat's other input. Use a new value for a different return. Omit it and every call creates.",
      +  "maxLength": 128,
      +  "type": "string"
      +}
  2. Addedv0.73.2

TDQS

A4.4/5.0
Behavior4/5

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

With annotations only declaring readOnlyHint=false and destructiveHint=false, the description carries useful extra weight: a merchant-opened return 'starts approved,' it 'does not move money or stock,' and the idempotency contract explains what a retry does and does not create. That is genuine behavioral context beyond the annotations. It stops short of stating permission requirements or what the created return object looks like beyond the idempotent replay case.

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

Conciseness5/5

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

Three sentences, front-loaded with the core action, then the money/stock boundary, then the operational retry rule. Every sentence adds information an agent needs to call this correctly, and there is no filler.

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 mutation tool with six parameters and no output schema, the definition covers the critical unknowns: default approval state, absence of financial and inventory side effects, and safe retry behavior. It does not describe the shape of the returned object or any permission prerequisites, which leaves a small gap for an agent that needs to act on the result.

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?

Schema description coverage is 67%, so the schema documents most fields itself, including a thorough idempotencyKey description and the constraint that lines cover only units already handed to the carrier or customer. The description largely restates the idempotency guidance already in the schema and adds no meaning for carrier, trackingNumber, note, or orderId. Adequate, but it does not compensate for the undocumented remainder.

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?

The opening sentence gives a specific verb and resource plus scope: 'Open a return on an order for items the customer is sending back.' It then names the sibling tools receive_return and refund_return and assigns them the restock and refund duties, so an agent can distinguish this tool from its closest neighbors without opening either schema.

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

Usage Guidelines5/5

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

It states explicitly when this tool applies (opening a return) and which sibling to use for the adjacent actions (receive_return for restocking, refund_return for the refund), which also implicitly says when not to use it for money or stock movement. It adds concrete retry guidance for timeouts and unclear failures, naming the exact recovery pattern.

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