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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses the upsert contract in detail: 'fields you pass replace, lists inside replace, sections you don't mention are kept; removeSections drops by title,' plus new-kit defaults ('empty standard sections plus the workspace's colors'). This is exactly the mutation semantics an agent needs to avoid clobbering data.

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 information is mostly load-bearing for a deeply nested schema, but it is delivered as one dense, unbroken paragraph that mixes usage, data model, and upsert semantics. Front-loading is good, yet the wall-of-text formatting hurts scannability.

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 complex nested-object tool with no output schema, the description is largely complete: it covers creation/editing rules, defaults, section kinds, and destruction semantics. Gaps remain around the top-level name/description/fromKitId parameters and any return shape, but the core invocation contract is covered.

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?

With only 50% schema description coverage, the description compensates well by explaining the section data model (title/kind/body/rules, swatches, faces, use/avoid, assets, links), the hex format, and how content.sections/uses/removeSections behave. It omits meaning for name, description, and fromKitId, which the schema only partially covers.

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?

The description opens with a specific verb+resource pairing, 'Creates a new brand kit, or edits one that is NOT the workspace's brand,' which immediately scopes it apart from the other napkin_brand_* siblings (get, list, apply, view). An agent can tell this is the drafting/mutation tool without opening the 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?

It gives explicit trigger conditions — 'Use it when someone asks you to put their brand together (from their site, a deck, or what they tell you) or to try a variation' — and states a clear negative boundary plus the workaround for the workspace brand. It stops short of naming the alternative tool (e.g. napkin_brand_apply) by name, so routing is implied rather than explicit.

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