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

Beyond the annotations it discloses that edits are draft-only with live preview and never reach visitors until publish, that stale_draft etag conflicts refuse the call, that unknown paths are rejected with the accepted list, that colours are normalised to hex, and that image settings copy the asset onto the help center. That is substantially more operational context than the destructive/idempotent/openWorld hints convey.

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 information is front-loaded: the scope sentence comes first, then draft/publish safety, then path syntax, then args and returns. It is dense and long, with somewhat nested parentheses, but virtually every sentence carries distinct guidance rather than restating the schema or annotations.

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 3-parameter, non-read-only tool with no output schema, the description covers the mutation's blast radius, the draft/publish lifecycle, prerequisite reads for ids and paths, a migration edge case, and the return contents (new ids, warnings, draft status and etag). An agent has enough to call it correctly and to relay results.

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%, but the prose adds real meaning: paths may target a single leaf or a whole group object, null clears a nullable setting, colour formats and the theme.darkColors pairing rule, the {source_url} shape for image settings, and the precise etag conflict semantics. The all-or-nothing ordering and positional error reporting is explained in the schema, and the description reinforces the workflow around 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 opens with a specific verb and resource ("Change document-level design settings in the draft") and enumerates the setting families covered: theme colours/fonts/corner radius/density, brand assets, meta/SEO, and per-page layout. It explicitly names the sibling it is not (helpcenter_update_template_region) and the related publish/get tools, so an agent can separate it from the other template-editing siblings 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?

It gives explicit when-to-use and when-not guidance: edit the draft here, publish only via helpcenter_publish_template and only when the customer asks, use helpcenter_update_template_region for region styling, and fetch ids from helpcenter_get_template. It also states a hard exclusion — v2 help centers only, classic ones return template_migration_required.

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