Skip to main content
Glama

Order: Validate Issues

diagnose_order_issue
Read-onlyIdempotent

[Order] [What it does] Read-only diagnosis of why DSers orders cannot be placed, paid, or fulfilled; reports per-dimension pass/fail results, non-blocking warnings, and resolutions. [When to use] Use when the user asks why an order is failing, or to check readiness before placing it with the supplier. Call this before place_orders_to_suppliers / placement to understand and resolve blockers. [When not to use] To actually place an allowed order, use the placement tool; this tool never places orders or edits data. [How to use] Exact dsers_order_ids mode and search-filter mode are mutually exclusive. Both modes require one concrete status and supplier_platform_id; all is rejected. Search mode evaluates one page of up to 100 orders. Exact IDs are looked up only in that supplier/tab pair, and a miss is per-order NOT_FOUND without retrying another supplier or tab. Other search filters cannot be combined with dsers_order_ids. search_by=dsers_order_id remains search mode. Item validation and platform-function checks use only items matching the selected supplier and tab. Only decision=allowed with complete=true conclusively permits placement — unknown or incomplete remains inconclusive even without a reported blocker. Dimensions whose checks are unavailable are reported in missing_checks, not treated as passing. fulfillable_item_ids contains supplier-orderable item IDs from the selected supplier/tab scope and supports initial placement from awaiting_order plus re-placement from cancelled and failed; seller-platform Fulfill restrictions are excluded from this supplier-ordering result. The supplier order-and-payment disable switch is evaluated per supplier_platform_id. CANNOT_ORDER_WITHOUT_SKU is evaluated for supplier apps that have unquoted items; a confirmed restriction is UNQUOTED_ORDER. AWAITING_ORDER_ITEM_PRODUCT_EMPTY_CANNOT_ORDER is evaluated for supplier apps that have zero-quantity items; a confirmed restriction is ZERO_FULFILLABLE_QUANTITY. MAX_CHAR_LEAVE_A_MESSAGE_TO_SUPPLIER is evaluated for supplier apps that have items with messages over 1000 characters; a confirmed restriction is SUPPLIER_MESSAGE_TOO_LONG. AWAITING_PAYMENT_MAKE_PAYMENT_BTN_DO_NOTHING is evaluated for all relevant supplier apps on awaiting-payment orders with zero cost; a confirmed restriction is AWAITING_PAYMENT_ZERO_COST. SHIPPING_COUNTRY_REQUIRED blocks placement when address.country is missing or blank, including a missing address; the order cannot be placed until a shipping country is configured. SHIPPING_METHOD_UNAVAILABLE is reported when no freight option is available for a mapped supplier product to the current shipping destination; it blocks placement until the supplier, product, or destination changes. SHIPPING_METHOD_REQUIRED is reported when a mapped supplier has available freight options but no shipping method is selected; a confirmed restriction blocks placement. ORDER_COST_EXCEEDS_REVENUE is a non-blocking warning when product cost plus shipping cost is strictly greater than order revenue on one complete, matching currency basis; it is omitted when those amounts cannot be compared safely and never changes decision, complete, or fulfillable_item_ids. Other platform-dependent checks that cannot be evaluated stay in missing_checks. [Side effects] Read-only; no order data changes. [Confirmation] Required per current configuration and not skippable. [Follow-up] If conclusively allowed and placement is the goal, proceed to the placement tool per its own confirmation rules; otherwise report the blocker or missing check and stop.

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": {
      "status": "<status>",
      "supplier_platform_id": "<supplier_platform_id>"
    },
    "name": "diagnose_order_issue"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryNoOptional order search text.
cursorNoOpaque next_cursor returned by a previous diagnose_order_issue search call.
statusYesRequired DSers order tab and item-evaluation scope. It limits both lookup and item evaluation to one concrete tab; all and omission are not supported. Copy from list_orders when combining with dsers_order_ids; do not invent another tab after NOT_FOUND.
countryNoOptional destination country code filter.
end_timeNoOptional Unix order creation end timestamp.
page_sizeNoOrders evaluated from one search page, up to 100.
search_byNoHow query is interpreted in search_filters mode. Exclusive of dsers_order_ids. search_by=dsers_order_id stays search mode.
sort_orderNoOrder creation-time sort order.desc
start_timeNoOptional Unix order creation start timestamp.
dsers_order_idsNoOptional exact DSers order IDs. Cannot be combined with search filters other than the required status. Paste JSON example: ["2088507008557908224"].
dsers_store_idsNoOptional DSers store IDs for search_filters mode. Search mode also requires supplier_platform_id. Paste JSON example: ["1999323491106619392"].
supplier_platform_idYesRequired supplier platform ID in both exact dsers_order_ids and search_filters mode; it limits the selected orders and evaluated items to that supplier. Copy from list_stores supplier_apps[].supplier_platform_id, list_orders, or get_order.

Output Schema

NameRequiredDescriptionDefault
ordersYesPer-order validation results
summaryYesDecision counts for this response
checked_atYesRFC3339 evaluation timestamp
paginationYesCursor pagination for search_filters mode
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.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, yet the description still adds real behavioral content beyond them: exact-ID and search modes are mutually exclusive, a miss yields a per-order `NOT_FOUND` with no retry against other suppliers/tabs, `allowed`+`complete=true` is the only conclusive permission, and unevaluable checks land in `missing_checks` rather than counting as passes. The one confusing element is '[Confirmation] Required per current configuration and not skippable' on a read-only diagnostic — it is never explained and reads like boilerplate that could mislead an agent about whether a prompt will appear.

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?

The bracketed headings front-load what/when/how well, which helps navigation. However, the '[How to use]' block is extremely dense and spends many sentences enumerating individual blocking codes (`CANNOT_ORDER_WITHOUT_SKU`, `ZERO_FULFILLABLE_QUANTITY`, `SUPPLIER_MESSAGE_TOO_LONG`, `AWAITING_PAYMENT_ZERO_COST`) that mostly restate output semantics an output schema could carry, diluting the actionable selection guidance.

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 12-parameter, two-mode, blocker-reporting tool the description covers mode selection, scope, decision semantics, and follow-up, which is close to complete. Since an output schema exists, the long per-code rule enumeration is surplus rather than necessary, and the unexplained 'Confirmation required' note is the sole real gap.

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 coverage is 100%, so the schema already documents all 12 parameters, making 3 the baseline. The description does add meaning beyond the schema — the two-mode exclusivity, the ban on combining search filters with `dsers_order_ids` in the description text, the requirement for a concrete `status`/`supplier_platform_id`, and the 100-order page limit — but it does not explain parameters the schema leaves unclear.

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 first line states a specific verb and resource: 'Read-only diagnosis of why DSers orders cannot be placed, paid, or fulfilled,' and names the outputs (per-dimension pass/fail, warnings, resolutions). It is explicitly distinguished from the placement sibling, so an agent can select it without opening another 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?

There are dedicated '[When to use]' and '[When not to use]' sections that name the alternative (`place_orders_to_suppliers`) and the condition that selects it ('use the placement tool' to actually place). The `[Follow-up]` section also tells the agent what to do after a conclusive `allowed` result.

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.