Skip to main content
Glama

Order: Browse Orders

list_orders
Read-onlyIdempotent

[Order] [What it does] Browses orders, returning order summaries, per-tab counts, and cursor pagination; it is the entry point for obtaining order IDs. Set only_count=true to return only those per-tab counts with an empty orders array and no next page. An explicit supplier_platform_id limits results to that supplier; omitting it searches across suppliers. [When to use] Use it when the user wants to find orders, see pending volume, or filter by store, buyer, or time, and whenever the agent needs real order IDs before reading detail or processing. For how many orders or tab volume only, set only_count=true and read counts; do not follow with a second browse unless the user then asks for the list. Trigger words: recent orders, pending orders, this buyer's order, problem orders, how many orders. [When not to use] For Failed/cancelled inspection or order-blocker repairs, use get_order. Ordinary Awaiting Order placement uses these list summaries plus diagnose_order_issue; it does not require a detail read for every order. To place orders, use place_orders_to_suppliers. For shipment tracking, use get_package_details. [How to use]

  • only_count defaults to false. Set true only when the user asks how many orders or tab volume. Then orders is always empty and is not proof of zero orders; use counts. Empty orders must not be copied into get_order or placement. cursor, page_size, and sort_order are ignored. Do not fan out a count call into an exact order-number scan.

  • supplier_platform_id is optional. When the user names no supplier, omit it: orders and returned line items are not limited to one supplier. The string 0 searches Unmapped only and still filters items to Unmapped. Copy a positive ID from list_stores supplier_apps[].supplier_platform_id when the user names a supplier, and never substitute a sales channel ID.

  • status is optional. Omit it by default when the user does not name a tab, and for exact order-number lookup; that returns cross-tab rows within the selected supplier scope in one call. Do not fan out tabs. An explicit status filters returned line items to that tab. Statuses are tab memberships, not exclusive states: an order can sit in several tabs, counts overlap and must not be summed into a total, and pending and awaiting order are distinct values that both belong in any summary.

  • Each line_items[] row exposes supplier_platform_id and tab_statuses. If this call omitted supplier_platform_id or status, copy the omitted field from the same line_items[] row into get_order. Mixed tab_statuses: pick the tab matching the user intent, else the first known value. Do not invent supplier/tab pairs. If tab_statuses is empty, do not call get_order; re-list with an explicit status. Do not fill item tabs from orders[].order_status.

  • Each row includes dsers_store_id and, when available, sales_channel_id; resolve recognizable store and supplier names from current account context. line_items[] includes verbatim seller title, SKU when available, quantity, and known fulfillable quantity. Its supplier rows include verbatim product/variant names, quantity, selected shipping method name, and supplier order number. Missing optional fields are unavailable, not zero.

  • other_supplier_platform_count summarizes items with other suppliers. has_other_supplier_items indicates whether any exist; other_supplier_items_count lists each supplier_platform_id, its tabs, and its item count. Only positive counts are included. Use it to explain the order's additional supplier items to the user.

  • Each row's order_status is the tab requested for that call when status was set; when status was omitted it is the first known item tab, not a complete status set or an exclusive whole-order state.

  • Money is reported in several bases: order income is authoritative in the seller-platform currency, the setting-currency amount may appear only as a labeled conversion, and item prices and supplier costs use the DSers default currency. Row money follows this request's supplier filter; when supplier_platform_id is omitted, that scope is not limited to one supplier.

  • To search multiple seller order numbers, set search_by=order_no and pass a comma-separated query, for example 1001,1002 or ABC-1001,ABC-1002. English and Chinese commas are accepted. Only the first 100 non-empty keywords are searched. Results match any supplied keyword as a substring, so 1001 can also match 10010; verify returned sales_order_number values before selecting orders. When both time fields are omitted, order-number lookups search all available non-archived order history through the end of today; ordinary browsing defaults to the last 30 days. Store, supplier, status, and time filters still apply. Pass next_cursor with the same query and filters to retrieve more results. only_count=true counts orders matching the same batch filter.

  • Pages hold up to 100 rows; pass the returned cursor back unchanged for more. [Side effects] None; read-only. [Confirmation] Not required.

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
queryNoOptional search text. For multiple seller order numbers, set search_by=order_no and separate values with English or Chinese commas, for example 1001,1002. Only the first 100 non-empty keywords are searched. Batch results match any supplied keyword as a substring; verify returned sales_order_number values before selecting orders. A single numeric value is treated as an order number when search_by is omitted or default.
cursorNoOpaque next_cursor returned by a previous call.
statusNoOptional DSers order-tab membership filter. Omit it by default when the user does not name a tab, and for exact order-number lookup; do not fan out tabs. An order matches when at least one item belongs to this tab; it can simultaneously belong to other tabs. pending and awaiting_order are distinct values; received selects the Received tab and can be copied into get_order tab_status.
end_timeNoOptional Unix end timestamp. Omitted or zero defaults to the end of today (23:59:59 in Asia/Shanghai). If only end_time is supplied, the start defaults to 30 days before today.
page_sizeNoItems per page, up to 100. Single exact order-number lookup resolves the matched order directly without paging; comma-separated batch lookup honors page_size and cursor.
search_byNoHow query is interpreted. Omit, or use order_no, for an exact lookup of a single numeric seller order number. For comma-separated seller order numbers, always set order_no: results match any supplied keyword as a substring and support cursor pagination. Both lookup modes search all available non-archived order history when both time fields are omitted. Omit status to search across tabs. Use dsers_order_id only for an exact DSers internal order ID.
only_countNoWhen true, return only counts for the current filters. orders is always empty and is not proof of zero orders; read counts. cursor, page_size, and sort_order are ignored. Set true only for how many / tab volume; omit or false when order IDs or a browse list are needed.
sort_orderNoCreation-time sort order.desc
start_timeNoOptional Unix start timestamp. For single exact or comma-separated batch order-number lookups, omitting both time fields searches all available non-archived order history. Otherwise an omitted or zero start_time defaults to 30 days before today. Store, supplier, status, and other filters still apply.
dsers_store_idsNoCopy DSers store IDs from list_stores. Optional. Paste JSON example: ["1999323491106619392"].
supplier_platform_idNoOptional supplier platform filter. Omit when the user names no supplier: orders and returned line items are not limited to one supplier. Use 0 only for Unmapped orders with Unmapped item filtering; otherwise copy a positive ID from list_stores supplier_apps[].supplier_platform_id.
sales_order_destination_country_codeNoOptional sales-order destination country code in ISO 3166-1 alpha-2 format, uppercase, for example US for United States or CA for Canada.

Output Schema

NameRequiredDescriptionDefault
countsYesCounts by DSers order tab
ordersYesOrder list rows
paginationYesStable cursor pagination
toolcall_response_atYesUTC timestamp when the Tool response was returned, formatted as RFC3339.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds behavior the annotations cannot convey: the default 30-day window, the all-history search when both time fields are omitted, the 100-row page cap, the fact that an empty orders array under only_count is not proof of zero orders, and overlapping tab counts that must not be summed. These are exactly the traps that cause wrong agent behavior.

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

Conciseness3/5

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

Bracketed section headers front-load purpose and routing well, but the body is roughly 600 words and repeatedly restates schema text (only_count, supplier_platform_id, batch search) almost verbatim. It is dense rather than bloated with filler, yet several bullets could be trimmed without losing decision-relevant information.

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?

For a 12-parameter browse tool with an output schema, the definition still covers defaults, pagination, currency bases, empty-vs-zero pitfalls, and multi-keyword lookup limits, so an agent can call it correctly on the first attempt. Nothing needed to select or invoke it is missing.

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 cross-parameter semantics beyond the schema: only_count suppressing cursor/page_size/sort_order, supplier_platform_id=0 meaning Unmapped-only, status as non-exclusive tab membership, and copying omitted supplier/tab values from line_items into get_order. Some of this text is near-duplicated from the schema descriptions, which keeps it from a 5.

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 ('Browses orders') plus the concrete return shape (order summaries, per-tab counts, cursor pagination) and positions itself as 'the entry point for obtaining order IDs'. It explicitly differentiates from siblings by naming get_order for detail/blocker work and place_orders_to_suppliers for placement.

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?

Has dedicated [When to use] and [When not to use] blocks with named alternatives per scenario (get_order for failed/cancelled, place_orders_to_suppliers for placing, get_package_details for tracking) and trigger phrases. It also gives the unusual exclusion that a count call should not be followed by a second browse, which is real routing guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.