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

Beyond destructiveHint=true, the description discloses that the operation is non-atomic, that per-item results are returned and successful items are kept, that it halts on the first error by default, and that failures require re-reading versions before retrying. It also states that publish=true triggers immediate HTML publication. That is exactly the sort of partial-failure semantics an agent needs and cannot infer from 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?

Five dense sentences with zero filler: scope first, schema relation second, side effect third, failure semantics last. Every sentence conveys an operational constraint. Minor friction only in that it is written in French while surrounding tool metadata is English.

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 high-complexity, destructive batch mutation with no output schema, the description covers limits, atomicity, partial-success retention, error default and retry procedure. What it does not describe is the per-item result shape (ids, error info) or how partial successes are identified, which matters given there is no output schema.

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 0%, so the description carries the burden, and it only explains expectedVersion, optional ref, publish=true and the stop-on-error default (and mentions the 25-item cap). The heavy nested surface — content, operations with their 9 op types and index/blockId/sectionId — is left to "même schéma que update_page", which forces a cross-tool lookup.

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?

"Modifier jusqu'à 25 pages avec leur expectedVersion" gives a specific verb, resource and batch scope, and the second sentence ties it to update_page plus an extra ref field. An agent can tell this is the batch/multi-page variant of update_page without opening either schema.

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 establishes the operating context (batch of up to 25, same schema as update_page, optional ref) and gives recovery guidance for failures. It never explicitly says to prefer update_page for a single page or apply_page_changes for a different flow, so the routing is implied rather than stated.

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