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

The annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the risk profile is pre-supplied. The description nonetheless adds real behavioral context beyond them: nothing reaches visitors until publish, edits land in a draft guarded by an etag (stale_draft), all-or-nothing application with per-position error reporting, and refusal when moving into a synced region whose copies conflict. It does not, however, explain why the operation is marked destructive or what exactly a rollback/discard path looks like.

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?

Front-loaded with the core capability, then workflow, then failure modes, then args and returns — a sound structure with no filler sentences. It is dense and repeats some schema text (index/parent_id semantics) and the add_template_components routing twice, which keeps it just short of a 5.

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?

With no output schema, the description still summarizes the return value (per-entry results with new ids, warnings to relay, draft status and new etag). It covers prerequisites (v2 only, ids from helpcenter_get_template), concurrency (etag), and the publish gate — everything an agent needs before calling a destructive draft mutation.

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; the description still earns credit for explaining the omitted-field semantics clearly (omitting region or parent_id keeps placement, so {id, index} alone reorders among siblings, parent_id null lifts to region top level) and that index counts positions after the lift. Much of this is mirrored in the schema's parameter descriptions, so it is additive but not wholly new.

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 (reorder/move) plus resource (template components) and enumerates the destination types: siblings, another region, into a Hero or Container, or out to the region's top level. It also routes the different intent (placing a component on another page) to helpcenter_add_template_components, so it is distinguishable from 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?

Gives explicit when-to-use context (editing the v2 design draft that the Template Editor previews) and when-not (classic help centers return template_migration_required; cross-page placement belongs to add_template_components). It also states the workflow expectation: hand the customer the Template Editor link and publish only when asked.

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