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

Annotations already declare the destructive, non-read-only profile, so the burden is lower. The description still adds real behavioral detail beyond them — 'Font sizes are kept' tells the agent exactly what is preserved when the theme is repainted, which is not derivable from the schema or annotations. It stops short of explicitly saying the previous theme styling is replaced/irreversible, so it is not a full 5.

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 core action and the alternate-tool routing are front-loaded in the first sentences; the theme catalog and verification hint follow. The six-item theme list is dense but earns its place because no enum exists in the schema. Minor padding in the flavor text of each theme name.

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 bulk-mutation tool with no output schema and full schema-description coverage, the definition supplies the affected scope, the preservation rule, the recommended default, the value catalog, an alternative tool, and a verification step. Nothing an agent needs to call it 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 goes further by enumerating the built-in theme keys (plain, editorial, stage, blueprint, warm, notebook) with a semantic gloss for each — effectively supplying the enum that the schema lacks (0 enums declared). This meaningfully constrains the required `theme` string. The `accent` and `workspace` semantics remain schema-only.

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 and resource ('Paints every slide of a deck with a theme') and enumerates exactly what is affected — slide background, headings, body typefaces, text colors. It is clearly distinguishable from the sibling write paths (napkin_draw updates, napkin_slide_update) that it explicitly routes away from.

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-prefer guidance ('Prefer "brand" ... unless the user asks for something else'), names the alternative for the adjacent use case ('For one-off colors or sizes on a single shape, use napkin_draw's `updates` instead'), and prescribes a verification step ('Check the result with napkin_slide_view'). Nothing is left to inference.

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