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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description usefully narrows that destructiveness by clarifying the live page is untouched until publish. It also discloses a rate limit ('only be updated once every few seconds') and the shell upload workaround, adding real context beyond the annotations. It does not explain the conflict-detection role of base_updated_at.

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?

Three sentences, zero filler, front-loaded with the core action before the supporting caveats about live state, rate limits, and shell uploads.

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?

Covers the draft/live distinction, rate limiting, and upload mode for a 3-param mutation tool, and an output schema exists so return values need not be explained. Minor gap: no mention of the concurrency/conflict semantics tied to base_updated_at, though the schema documents it.

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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning for html ('omit html to upload the file, as with create_page'), which the schema does not convey. base_updated_at conflict behavior is left to the schema.

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?

States a specific verb and resource ('Replace a page's draft') and immediately disambiguates scope by noting the live page is unaffected until publish_page. An agent can distinguish this from publish_page and create_page without opening a 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?

Tells the agent when this applies (draft edits, not live changes) and routes to publish_page for publishing, plus names create_page for the shell-upload pattern. It stops short of explicit when-not-to-use conditions, but the context is clear.

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