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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds substantial context beyond them: the draft/live-preview boundary, the publish gate, the classic-help-center failure mode (template_migration_required), etag optimistic locking with a named error, and a warning that published scripts run for every visitor so code should come from a trusted source. That is exactly the behavioral detail an agent needs before mutating a template.

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 mutation semantics, then scope, then safety — a sensible ordering. It is dense but nearly every sentence carries information; the 'Args:' block is the weakest part since it re-enumerates parameters already documented at 100% coverage in the schema.

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 14-parameter destructive mutation with no output schema, the description covers the return value ('what each entry did (new ids), warnings worth relaying, and the draft status with its new etag'), the concurrency model, and the credential/lifecycle context. Nothing an agent needs to invoke this correctly is missing.

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, but the description adds two facts the schema does not state: 'Fields left out keep their value' (PATCH rather than replace semantics) and that supplying src, inlineBody or htmlBody switches the script to that kind (mutually exclusive mode switching). The Args list otherwise largely restates the schema, which keeps it from a 5.

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 ('Change one script') and enumerates exactly what can be changed (code, position, pages, label, loading flags, enabled), which separates it cleanly from helpcenter_add_template_script and helpcenter_remove_template_script. It even names the underlying guide operation (`update_script`), so there is no ambiguity about what call this is.

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?

Explicitly states the edit lands on the design draft, that nothing reaches visitors until helpcenter_publish_template, and that publishing happens only when the customer asks — a clear when/when-not rule with the alternative named. It also gives prerequisites (v2 help centers only, ids from helpcenter_get_template, stale_draft on etag mismatch) that route the agent correctly.

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