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

The description adds meaningful downstream context the annotations do not carry: the saved voice is "enforced by check_copy and check_edit", and the notes are constraints the agent must follow when designing. What it never discloses is the upsert contract — whether supplying an id/name merges into an existing kit or replaces it wholesale, and how partial nested objects (colors, voice) are treated. For a mutation of nested objects with only minimal annotations, that is a material omission.

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?

One front-loaded sentence with the action first and the field inventory after; the parentheticals (hex, list_fonts/add_google_font, check_copy/check_edit) each carry real information rather than padding. It runs long and slightly list-like, but nothing is redundant.

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 9-parameter, all-optional, nested-object mutation with no output schema, the description covers the domain fields well but leaves the operational core unexplained: identity/upsert semantics and the default-true useInProject side effect on the project brand. An agent could call it, but not confidently predict what a partial payload does to an existing kit.

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 description coverage is only 33%, so the description has to compensate, and it partly does: it clarifies colours are hex, fonts are heading/body families sourced from list_fonts, and notes are do/don't references. It adds nothing about the two completely undocumented parameters (id, name) or how id, name, projectId and useInProject interact — precisely the parameters that determine create-vs-update behaviour.

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 pair and resource ("Create or update a brand kit") and enumerates the constituent parts: colours, heading/body fonts, logo, voice, DNA notes. An agent can tell this apart from list_brands/get_brand/delete_brand, though it does not explicitly distinguish itself from import_brand or set_project_brand, which touch overlapping territory.

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 one real prerequisite chain — fonts must be "any family from list_fonts; add Google fonts first" — which is actionable ordering guidance. Beyond that there is no when-to-use/when-not guidance: nothing says whether to call this versus import_brand, or when to prefer set_project_brand over the useInProject flag.

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