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

The annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds material context the agent cannot get from them: the revision-based optimistic-concurrency guard ('if the list changed since, nothing is written and the current revision comes back'), the fact that only working order changes while readers see the last approved version, and the privacy note. That is exactly the kind of disclosure annotations cannot carry.

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 core action is front-loaded in the first clause, and each subsequent sentence carries distinct information (limit, concurrency, visibility, privacy). Slightly dense in a single paragraph, and 'Private lists stay private' is the weakest sentence, but nothing is 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 five-parameter mutation with no output schema and annotations covering the safety profile, this is close to complete: it covers scope, limits, ordering, concurrency failure, and visibility effects. The one gap is the success return value — it explains what comes back on a revision conflict but not what a successful call returns, which matters for an agent chaining further revision-based calls.

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 100%, so the schema already documents all five parameters and the baseline is 3. The description still adds meaning beyond it by explaining that itemIds is applied 'in the order given', that the 100 cap is a hard limit, and by spelling out the revision failure semantics ('nothing is written and the current revision comes back'), which turns a terse schema line into actionable behavior.

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 and resource ('Place up to 100 picks right before or after another pick on the same list, in the order given') plus a scope qualifier ('without sending the whole list'), which is far more than a restatement of the name. It stops short of naming the closely related siblings move_items and reorder_items, so an agent must still infer the boundary.

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?

'Use it on long lists, or to move a few picks' gives a real usage context, so this is better than nothing. But there is no when-not guidance and no explicit contrast with move_items or reorder_items, which are the most likely wrong picks in this sibling set. The routing decision is left implied.

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