Doco Batch Edit

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

Annotations already cover the write and destructive nature (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the bar is lower. The description adds genuinely useful behavioral context beyond those flags: atomicity ('全有或全无' all-or-nothing) and the server-enforced base_version semantics with auto-read when omitted. This tells the agent how the operation behaves at execution time. It stops short of describing rollback/error behavior or the consequences of the destructive ops, but it meaningfully supplements the annotations.

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?

Two dense sentences with the most important facts front-loaded: transaction scope and atomicity come first, followed by the op array shape, then the base_version behavior. There is no filler or repetition of schema fields. It is slightly compressed in a way that assumes familiarity (e.g., the '...' in the op shape), but every clause earns its place.

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?

An output schema exists and annotations cover the safety profile, so return values and destructive/write hints are handled. The notable gap is the operation payload structure: the description's '{op: insert|replace|delete, ...}' plus the schema's additionalProperties-{} items leaves the actual mutation fields (e.g., where to insert, what replacement content is, which path is targeted) undocumented. For a destructive batch tool this is a significant omission. Sibling routing guidance is also absent. Adequate but with clear gaps.

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%, setting the baseline at 3. The description adds real value beyond the schema: it specifies the operation item shape ({op: insert|replace|delete, ...}) which the schema's generic items object with additionalProperties:{} leaves entirely open, and it clarifies base_version as server-required-but-auto-read, going beyond the schema's 'Document version read before the protected write'. The idempotency_key already has a schema description, and the description adds nothing further there, which is acceptable.

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: 批量编辑 (batch edit) targeting a doco document, scoped to 1–100 operations with explicit op types (insert|replace|delete) and all-or-nothing transaction semantics. This is clear and actionable, but it does not explicitly differentiate from sibling tools such as doco_update_document or the block-level edit tools, relying on the 'batch' framing and the tool name itself to signal distinction.

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?

Usage context is implied rather than stated: the 'single transaction / all-or-nothing' and '1–100 operations' framing signals this is for atomic multi-operation edits, which is a meaningful cue. However, there is no explicit when-to-use vs when-not-to-use guidance, no named alternatives (e.g., doco_update_document for a single edit, doco_patch_block/doco_insert_blocks/doco_delete_block for finer-grained operations), and no mention of prerequisites such as document existence or permissions.

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