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

Annotations already flag destructiveHint=true and non-idempotency; the description adds the ownership constraint, the partial-update contract, and the non-obvious image gate — pictures are kept but not shown until the owner confirms them in the preview. It also notes that header links replace the current set, though the schema is what says this. It stops short of describing what a successful call returns or how failures surface.

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?

Purpose is front-loaded and each sentence carries information, but the images_are_ours clause is long and largely restates the schema description, and the draft_id sentence is buried mid-paragraph. Dense run-on phrasing costs it some clarity.

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 12-parameter, all-optional mutation tool with no output schema, the description covers permissions, partial-update semantics, the preview path, image confirmation, and language scope. Gaps remain around return values and what happens to unmentioned settings, but the essential calling context is present.

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 already 100%, so the baseline is 3, but the description adds cross-parameter meaning: draft_id pairs with an unclaimed preview versus site for a kept site, images_are_ours is a permission assertion rather than a display toggle, and languages governs the site's own UI words like Previous/Next/Search. That goes beyond the per-field schema text.

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 ('Change how a site looks') and immediately enumerates the concrete facets: theme, main colour, typeface, header links, logo and icon. That enumeration distinguishes it cleanly from content-editing siblings like apply_edit, propose_edit, and publish without needing to name them.

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 operational guidance: 'Only the site's owner can do this', 'Give only the things to change', and the rule that draft_id is used on an unclaimed preview while site is used for a kept site. It never explicitly contrasts itself with siblings such as apply_edit or propose_edit, so there is no stated when-not-to-use condition.

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