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

Annotations declare readOnlyHint=true and destructiveHint=false, but the description describes a state-changing cancellation ('Cancel Order', 'do not cache or automatically retry writes'), which directly contradicts them. This is the most consequential possible discrepancy for an agent deciding whether to gate the call behind user confirmation. The useful context it does add ('Cancellation is not a refund', auth requirements, no-retry policy) cannot offset a safety-flag inversion.

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

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

Five short sentences, no filler, with the purpose and the user/authorization scope front-loaded before the operational cautions. Each sentence carries a distinct constraint; only the ordering of the caution clauses could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-output-schema mutation tool this covers auth, retry policy, and the not-a-refund caveat, but it omits the two undocumented parameters and, critically, gives no confirmation/irreversibility guidance that matches a cancel operation. Combined with annotations that misrepresent it as read-only, an agent lacks what it needs to call this safely.

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

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

Schema description coverage is 50%: aliOrderId and confirmCancel are documented, but remark and cancelReason have empty schema descriptions and the tool description says nothing about them. With half the parameters undocumented and an additionalProperties: true schema, the description needed to compensate and does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete verb and resource ('Cancel Order') scoped to 'the currently authenticated Nexscope user' and to 1688, which distinguishes it from siblings like nexscope_data_alibaba1688_order_status or nexscope_data_alibaba1688_confirm_receive. It does not explicitly name a sibling, so it stops short of a 5.

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

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

It gives real preconditions: an ACTIVE unexpired 1688 authorization owned by the current user, eligibility dependent on the current order state, and 'do not cache or automatically retry writes.' What is missing is an explicit routing instruction (e.g. 'call order_status first to check eligibility' or 'use payment_url instead if the order is unpaid').

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