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

Annotations only say destructiveHint=true, readOnlyHint=false, openWorldHint=false; the description goes far beyond by disclosing the merge semantics that make this destructive — 'fields you pass replace, lists inside replace, sections you don't mention are kept', plus removeSections drops by title, and new kits inherit the workspace's colors. This is exactly the kind of behavioral context that prevents accidental data loss.

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 create/edit decision and the workspace-brand prohibition before the dense content-model exposition, which is the right ordering. The remaining prose is a long em-dash-heavy run of clauses, but nearly every sentence carries information an agent needs to build a valid kit payload, so the length is largely earned.

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, so the description must carry the full burden — and it covers the mutation semantics, the content model, the workspace-brand boundary, and the 'give every rule a why' convention. It omits the return shape/identifier of a newly created kit, which is a minor gap for a creation tool whose caller likely needs the new kitId.

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 coverage over a deeply nested six-parameter model, the description compensates well: it defines the section content model (title/kind/body/rules/swatches/faces/use/avoid/assets/links/layouts), explains the upsert-by-title behavior of content.sections, and clarifies that content.uses references swatch or face NAMES. It does not document name, description, workspace, or fromKitId directly, but the schema does cover those.

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+resource pair ('Creates a new brand kit, or edits one that is NOT the workspace's brand') and immediately scopes it against the workspace brand, which is exactly the confusion an agent would have. An agent can distinguish this from napkin_brand_apply / napkin_brand_get 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 clear triggering contexts ('when someone asks you to put their brand together... or to try a variation') and an explicit prohibition with a workaround ('You can't change the workspace's brand itself — make a draft and tell the user they can choose it'). It stops short of naming sibling tools (napkin_brand_apply, napkin_brand_examples) as alternatives, so it is clear context without explicit routing.

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