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

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds authentication and role requirements (需要登录·主办方), a required prerequisite call, a confirmation step, silent-ignore behavior for out-of-scope IDs, and a verification requirement to inspect the returned complete list. These are meaningful behavioral traits not captured by structured fields.

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?

The description is one dense but front-loaded paragraph that opens with the authentication/role requirement and immediately states the required workflow. Every clause earns its place by covering prerequisites, ordering semantics, edge cases, and the alternative tool; there is no filler.

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 mutation tool with two parameters and no output schema, the description covers authentication, the prerequisite list call, the exact ordering contract (complete list, sortOrder from 0), silent-ignore and missing-item behaviors, verification of the returned list, and the sibling tool for other operations. Nothing essential for correct invocation is missing.

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 coverage is only 50% (ids has no schema description), but the description fully compensates: it explains that ids must contain the complete new order of all material IDs, with sortOrder written from 0, that missing items cause sort-number collisions, and that out-of-scope IDs are silently ignored. This adds crucial meaning beyond the schema.

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 specific verb (排序/reorder) and resource (活动资料/activity materials), and explicitly distinguishes itself from siblings by saying '只排序，改名/可见性update_activity_material' and naming list_activity_materials as a prerequisite. An agent can identify exactly what this tool does without opening other schemas.

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 an explicit workflow: first call list_activity_materials, then supply the complete new order of all material IDs and confirm, with sortOrder written from 0. It warns that missing items collide with sort numbers and that out-of-scope IDs are silently ignored, and it names the alternative update_activity_material for renaming/visibility.

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