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

Annotations already declare readOnly/idempotent/non-destructive, so the baseline is low, yet the description adds real behavioral context: output is markdown containing role colors, site tokens, font stacks, type styles, radii, spacing, shadows and motion, plus caveats and source links. The determinism guarantee ('values are copied from the specs, nothing is invented') is a trait no annotation conveys and directly affects how much the agent should trust the output.

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?

Dense but front-loaded: purpose and trigger first, then return contents, then the determinism guarantee, then the default precedence rule, then the save-before-implementing directive, then the exclusion. Each sentence carries distinct information and none repeats the schema or the annotations.

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?

There is no output schema, but the description fully specifies the return artifact and its constituent fields, plus the caveats and source links it includes. Combined with the precedence defaults and the save-to-disk guidance, an agent has everything needed to call this correctly 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?

Schema coverage is 83 percent, so the schema already explains sites, product, notes and the three *_from fields. The description nonetheless adds the default assignment rule the schema never states: the 1st site supplies color, the 2nd type, the 3rd layout, overridable via color_from/type_from/layout_from. That is genuine added meaning, though it does not elaborate formats or the notes/product parameters.

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 names a specific verb and artifact ('compose' a 'markdown brief with exact values') and scopes it to two concrete scenarios: mixing references across sites or producing a ready-to-save brief from one site. The closing clause explicitly contrasts it with get_design and get_design_md, so an agent can distinguish it from siblings without opening any 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 a triggering condition ('Use this when the user wants a direction that mixes references...'), states the negation with a named alternative ('Not for a single site's raw values (use get_design or get_design_md)'), and adds a workflow prerequisite ('Save the result to disk before implementing'). When-to-use, when-not, and alternatives are all present.

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