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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds important beyond-schema behavior: expectedRevision is used for conflict detection, omitted existing pages are deleted, and deletion requires permission. These are specific operational consequences an agent needs before invoking a destructive update.

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 description is three sentences, front-loads the core update action and conflict detection, then immediately states the destructive page-deletion rule and guide reference. There is no redundant restatement and every sentence adds useful information.

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?

The tool has 8 parameters, nested page objects, destructive behavior, and an output schema. The description covers the critical risky behaviors: conflict detection, deletion of omitted pages, deletion permission, and where to find authoring syntax. It does not explain summary or give page-tree shape guidance, but the output schema and get_authoring_guide reference reduce the remaining gap.

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 only 25%, so the description must compensate. It clarifies expectedRevision's conflict-detection role and the destructive semantics of omitting pages, but it does not explain summary or the page object structure in detail. It partially compensates for the low schema coverage rather than fully resolving it.

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: updating MDX document content and the authoritative page tree. It also adds scope through expectedRevision conflict detection and page deletion behavior. It does not explicitly differentiate itself from siblings such as create_document or update_project, so a 4 is appropriate.

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?

The description implies this is for modifying an existing document and points to get_authoring_guide for supported interactive component syntax. However, it does not state when to use this tool versus create_document, update_project, or other sibling tools, and provides no explicit exclusions.

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