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

Annotations only say destructiveHint=true and not read-only; the description goes well beyond that by promising atomicity, stating that internal IDs are regenerated, that mode 'auto' edits a published page immediately while 'draft' preserves an explicit draft, and that the rest of the site stays intact. It does not cover failure behavior such as what happens when expectedVersion is stale, which is the main risk for a destructive tool.

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 content is front-loaded and dense with no filler sentences, each clause adding a constraint or behavior. It is written as one long run-on sequence, which slightly hurts scanability for the mode and ID-renaming facts that matter most.

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 destructive, mutation-heavy tool with a nested schema and no output schema, this covers the operation's shape, sourcing, positioning, versioning and draft-vs-live effects. The remaining gaps — the unexplained 'live' mode, version-conflict errors, and the return value — are minor but real.

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 whole burden and mostly succeeds: it marks expectedVersion as mandatory, explains beforeId/afterId as the positional anchor, maps source.componentId to the gallery versus source.section/element to native content, and defines append versus absolute positions. It omits the third enum value 'live', which appears in the schema but is never mentioned, and does not clarify the pageId semantics beyond 'existing page'.

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+resource pairing ('Insérer atomiquement des sections et/ou éléments dans une page existante') and spells out the two source kinds it accepts, which is far more informative than the name alone. It never names the neighbouring tools it should be distinguished from (insert_html_section, apply_page_changes, update_page, batch_update_pages), so sibling differentiation is left to inference.

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 gives real conditional guidance inside the call: an element needs targetSectionId plus placement 'append' OR explicit desktop/tablet/mobile positions, and mode draft versus auto is explained with consequences. What is missing is any statement of when to choose compose_page over update_page, insert_html_section or apply_page_changes, so an agent must guess the boundary between the insertion tools.

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