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

Annotations are minimal (only readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the burden and delivers: atomicity ('all-or-nothing'), field-level preservation ('Only supplied fields change — unrelated properties are preserved'), reparent semantics ("" to detach), the immutability of element types, and the Pro-or-trial entitlement. This is substantial value beyond the annotations, with no contradiction.

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 and key constraints are front-loaded in one dense, information-rich sentence followed by two short constraint statements. Every clause earns its place — no filler, no repetition of schema content, and the most decision-relevant facts (type immutability, Pro requirement, preservation semantics) are stated compactly.

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 mutating batch tool with no output schema, the description covers the essential operational aspects: batch size limit (from schema, reinforced as 'up to 100'), atomicity, preservation of unspecified fields, source of uids, type immutability, and workspace tier. Minor gaps remain around failure behavior for invalid uids and the exact return value, but nothing an agent critically needs to invoke it correctly.

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%, but the description compensates by mapping every operation to its parameters: move (x/y), resize (width/height), restack (z_index), recolor (color with hex-fill and auto re-derived borders), reparent (parent_id with detach semantics), and connector path/arrow/label. This adds meaning beyond the raw schema, though individual parameter details like z_index ordering or numeric bounds are not described.

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?

States a specific verb+resource ('Update up to 100 whiteboard elements in one all-or-nothing call') and enumerates exactly what can be changed (move, resize, restack, retext, recolor, reparent, connector properties). It also names the key limitation ('element types cannot be changed'), which distinguishes it from sibling tools like convert_whiteboard_element and create_whiteboard_elements.

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?

Provides clear operational context: uids come from get_whiteboard, and a Pro or trial workspace is required. It states the constraint that element types cannot be changed but doesn't explicitly name the alternative tool for that scenario, so it stops short of full when-to-use-vs-alternatives guidance.

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