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

Annotations already cover openWorldHint=false and readOnlyHint=false, and the description reinforces those with 'fetches nothing from YouTube... and publishes nothing' and 'Bardiyah stores the number you send and never works one out itself'. It also discloses workspace scoping ('a script the signed-in user can edit') and deterministic storage of the rating, which annotations cannot express.

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 critical constraints (append, no external calls, mandatory final section) are front-loaded and the format spec is precise. It is somewhat verbose and repeats the 'stores the number, never computes one' idea in two separate sentences, which costs a point.

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 6-param mutation tool with no output schema, the description covers purpose, side effects, dialect, and the non-obvious mandatory formatting rule. The only gap is that it never says what is returned (section id, updated script, etc.), which the agent cannot infer without an output schema.

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 real constraints beyond it: the exact section title 'Viral Score', the required body structure (bold 'N / 10' line, dialect-specific header, 3-5 bullets, weakness line), and the requirement that the sent rating match the section. That is substantive value over the schema's field-level docs.

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 (add), resource (a section — defined inline as 'a titled piece of the script'), and target (the end of a specific script). This is clearly separable from update-script, which edits existing content rather than appending sections.

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?

'Use this to draft or extend a script one section at a time' gives a clear usage context, and the mandatory final 'Viral Score' section rule is unambiguous. It doesn't explicitly say when to prefer this over update-script, but the append-only framing makes the split obvious.

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