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

Annotations already declare destructiveHint=true, so the lower bar applies, yet the description still adds substantial behavior: atomicity of the whole batch, a ~1 MB request ceiling, the guarantee that only listed fields change and 'leurs voisins sont conservés', group/ungroup effects via @ref.groupId with geometry and rendering untouched, and the fact that a new snapshot is returned. It stops short of stating what happens on a stale or mismatched snapshot, which is the key failure mode for an optimistic-concurrency 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?

The definition is a single dense paragraph that front-loads the core concept (atomic batch of targeted changes) before drilling into set/unset, refs, grouping, and source semantics. Nearly every sentence carries operational information, though the run-on packing of syntax examples and ref shortcuts makes it harder to scan than a lightly sectioned version would be.

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?

With no output schema, the description correctly compensates by stating 'Réponse courte avec nouveau snapshot'. Combined with the atomicity guarantee, size limit, and draft/published divergence rule, an agent has enough to call this correctly. What remains unstated is snapshot-conflict/error behavior and what pageId refers to, minor against an otherwise complete picture.

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 must carry parameter meaning and largely does: set is defined as path-to-value with a concrete example, unset is defined as removal of optional properties, the .0 and [0] index notations are accepted, link and group reference paths are spelled out, source draft/published behavior is explained, and snapshot is marked mandatory. Only pageId is left entirely unexplained, which is a small but real gap.

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 opens with a specific verb and resource in French: 'Modifications ciblées en UN lot atomique' on a page, with set/unset semantics and a stated batch scale ('4, 40, 400 ou plus'). The atomic-batch framing implicitly separates it from single-edit siblings like update_page or edit_live_page, but no sibling is named, so the differentiation is inferred rather than explicit.

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?

Useful decision guidance is present for the source parameter: 'draft ne publie pas ; published modifie le site publié et préserve le brouillon divergent', and 'snapshot obligatoire' signals the precondition. However, there is no explicit when-to-use-this-vs-alternatives guidance against update_page, batch_update_pages, or edit_live_page, which is the main ambiguity an agent faces with this large sibling set.

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