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

Annotations already declare destructiveHint/idempotentHint, but the description adds real context beyond them: the change only touches a draft, nothing reaches visitors until helpcenter_publish_template, classics return template_migration_required, and stale etags produce stale_draft. It also flags that the Template Editor link should be relayed to the customer for review, which is behavioral guidance no annotation conveys.

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 action and the alternative, then scope, then args, then return shape — a clean hierarchy. Slight redundancy: the etag/stale_draft behavior appears in both the prose and the schema description, and the publish reminder runs long.

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?

No output schema exists, and the description covers the return value (what each entry did, warnings, draft status with new etag). Combined with draft/live semantics, error modes, and v2 gating, an agent has everything needed to call this correctly in a multi-step template edit workflow.

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 earns above that by giving provenance for `id` ('Ids come from helpcenter_get_template') and restating the etag lock behavior as a workflow rule. The agent_key credential semantics are left entirely to the schema, which is acceptable given how thorough that schema description is.

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 ('Delete one custom CSS block from the draft') and immediately distinguishes itself from the near-sibling helpcenter_update_template_css by naming the non-destructive alternative. An agent can pick this tool over the ~58 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 an explicit when-to-use-this-instead condition ('To see the design without it first, switch it off with helpcenter_update_template_css (enabled:false) instead') plus a workflow constraint ('publish only when they ask') and an applicability gate (v2 help centers only). Exclusions and alternatives are both stated.

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