preview_batch_actions

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds value by stating 'makes no changes' explicitly and clarifying the input format (exact JSON action structures), which goes beyond the schema. It also demonstrates that target_folder uses localized values (like '已删除'), a useful real-world nuance. However, it doesn't detail what the returned digest contains or how batches over 50 are handled.

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 compact and front-loaded with the core purpose in the first sentence. The JSON examples are highly instructive and earn their space. It could arguably be slightly tighter, but each element adds real value with 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?

Given there is an output schema covering the return value, the description's job is to cover inputs and behavior, which it does thoroughly. It explains the action schema, supported action types, count limits, and the no-op guarantee. Minor gap: doesn't specify what a valid uid looks like or confirm the action-type set is exhaustive, but overall it's strong for a tool of this complexity.

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 0%, and the schema only provides a loose 'additionalProperties: string' object type with no field names or meaning. The description fully compensates by specifying the exact action schema (action/uid/source_folder/target_folder/state), giving concrete JSON examples for each of the three action types, and clarifying the 1-50 count constraint. This is exemplary parameter documentation.

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 clearly states the verb (preview), resource (batch actions: move, trash, read-state), scope (1-50 actions), and outcome ('returns a digest and makes no changes'). It also distinguishes from unlikely siblings by noting the digest/no-changes behavior, setting it apart from execute_batch_actions.

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?

The description clearly states when to use this (to preview actions before executing) via the 'makes no changes' clause, and the examples demonstrate the three supported action types. However, it doesn't explicitly name execute_batch_actions as the alternative to use when wanting to actually apply changes, though this is strongly implied by the sibling context and 'makes no changes' phrasing.

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