yuque_batch_update_toc

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

With no annotations the description carries the full burden, and it does meaningful work: the destructive-op safety gate (confirm token), the auto-reuse behavior of createTitle, and name-based lookup via target_title. It omits failure semantics — whether ops are atomic, what happens if one op in the array is invalid — which matters for a batch mutation.

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?

Dense and front-loaded: the interaction model comes first, then the action list, then the warning, then the alternative tool. Some of the ops enumeration duplicates the schema description, which is the only waste.

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 3-required-param batch mutation with no output schema and no annotations, the description covers the destination, the safety gate, action semantics, and the sibling alternative. Missing only return/error behavior, which the absence of an output schema leaves unaddressed.

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% and the ops/confirm/book_id descriptions already document the accepted action names and the confirm requirement, so the description largely restates structured data. Baseline 3 is correct; it adds no format or syntax detail 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?

States a specific verb+resource ('Batch update repo TOC') and immediately clarifies the unusual interaction model ('Agent provides ops plan, tool executes only'), then enumerates the five supported actions. An agent can tell this apart from the singular yuque_update_toc and from the web_* catalog tools.

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?

Explicitly routes cross-book copy to yuque_copy_doc and states the confirm='RESTRUCTURE' precondition for remove/move. It stops short of explaining when to prefer this batch tool over yuque_update_toc for a single-node change, which is the most likely sibling confusion.

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