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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral details: the max 100 item limit, the strict refusal (no partial moves) when target columns don't match, and the never-silently-drops-properties guarantee. It also clarifies that newParentId=null means workspace root. These go beyond the structured annotations without contradicting them.

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 a single dense paragraph that front-loads the core purpose and limit, then clearly separates the two modes with semicolons and conditional clauses. Every sentence adds necessary information—no filler, no redundancy. The structure makes the mutual exclusivity and refusal behavior easy to parse.

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 the tool's complexity (two modes, a max limit, a strict refusal condition, and an output schema that is present), the description is remarkably complete. It covers all operational aspects an agent needs to call it correctly: the modes, the constraint, the failure behavior, and the root-parent semantics. Annotations already handle safety, so nothing critical 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 description coverage is 100%, so all four parameters are documented. The description adds meaningful semantic context: it links newParentId and targetDatabaseId to the two mutually exclusive modes, explains that exactly one must be given, and clarifies that newParentId can be null for workspace root. This supplements the schema's per-field descriptions with cross-parameter relationships and usage constraints.

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 (move), resource (items), and scope (multiple, max 100). It clearly differentiates from the sibling move_item by being the batched version, and distinguishes the two modes (sidebar reparenting vs cross-database). The purpose is unambiguous and directly tells an agent what this tool does.

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 explains the two modes and the exact constraint that exactly one of newParentId or targetDatabaseId must be given. It references move_item as the single-item counterpart, implying single-item moves should use move_item. It also describes the refusal behavior for incompatible cross-database moves. It doesn't explicitly list when-not-to-use alternatives beyond that, but the context is clear enough.

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