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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: the two kit kinds and their token namespaces, the `guidelines` fallback with precedence rules ('let the kit win where they disagree'), the non-blocking nature of `brand_warnings`, and the no-kit return shape. This is rich behavioral disclosure for a read tool.

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?

Purpose and the 'call before building' directive are front-loaded, and the dense sentences each carry distinct information about return shape and precedence. It is long, but the length is earned by an undocumented return structure; slight trimming would still help readability.

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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: both kit kinds, their fields, tokens_css usage, guidelines, warnings, and the empty case. An agent has everything needed to call it and act on the result.

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?

Only one optional parameter and schema description coverage is 100%, so the schema already fully documents workspace_id (including personal-space fallback). The description adds a mild contextual hint ('the workspace_id you were asked to publish in') but no syntax or format detail beyond the schema, which is the baseline-3 case.

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 ('the active workspace's brand kit') and immediately differentiates from the write sibling by describing the read shape, including the empty case (`has_brand_kit: false`). An agent can tell this apart from set_brand_kit/set_brand_guidelines without opening either 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?

Explicitly instructs when to call it ('BEFORE building or restyling any page, report, deck or dashboard') and with which argument ('the workspace_id you were asked to publish in'). It also gives downstream actions: read guidelines where the kit is silent, fix every `brand_warnings` entry before reporting done. 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.