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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world, and the description reinforces this consistently by disclosing PATCH semantics ('Omitted fields stay unchanged'), the optimistic-concurrency requirement (expectedRevision), the frozen-theme lock, and the fact that published pages are untouched. What it omits is failure behavior on a stale revision and any auth/capability caveat, so it is strong but not exhaustive.

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 tight sentences with the editable surface front-loaded and constraints trailing, no filler. It is dense with semicolon-joined rules, which is efficient but slightly compresses the distinction between the mutually exclusive links and linkUpdates paths.

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 4-parameter, deeply nested mutation tool with an output schema, the description covers the tricky nested semantics and the concurrency contract without needing to explain return values. The remaining gaps are draftCapability and stale-revision error handling, which matter given the explicit expectedRevision precondition.

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?

Top-level schema description coverage is 0%, so the description carries the burden and mostly delivers: it explains links vs linkUpdates vs socials replacement semantics, translation merging, and expectedRevision. However draftId and especially draftCapability (a 64-hex token parameter) are never explained anywhere, and name/tagline/avatar/design are only implied by 'profile, public avatar... freestyle appearance'.

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?

Opens with a specific verb and resource ('Edit a private draft's profile, public avatar, social icons, links, translations or freestyle appearance') and enumerates the exact editable surfaces, which separates it from create_page_draft, get_page and list_pages without naming them. The closing clause 'Changes never directly update a published page' further distinguishes it from the publication siblings.

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?

Gives explicit parameter-level routing: 'Use linkUpdates for existing link cards on mixed-card pages; links replaces a complete link-only list', and equivalent rules for socials, secondaryLanguages and translations. It also states exclusions ('Commerce, domains, calendars and file uploads are unsupported') and the precondition 'Requires latest expectedRevision', leaving little to inference.

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