aura_use_design_system

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

With no annotations, the description carries the full behavioral burden. It implies some deliverable ('token starter CSS plus copy order'), but does not say whether the tool is read-only or mutating, whether it writes files, whether it requires an id/slug, or what the response contains. For a tool whose name suggests an action ('use'), this is a meaningful gap.

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?

A single compact sentence with the resource front-loaded after the verb. No filler, though the parenthetical 'tokens first, then markup' is cryptic rather than clarifying, slightly reducing its value.

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 and no annotations, so the description should explain the return shape and the id/slug semantics; it does neither beyond a vague mention of 'token starter CSS'. An agent lacks enough to invoke this correctly with confidence.

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?

Two parameters (id, slug) exist with 0% schema description coverage, and the description mentions neither. It does not clarify how id and slug differ, whether either is required in practice (both optional per schema), or what happens if both are omitted — so it fails to compensate for the coverage gap.

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 verb ('Apply') and a resource ('DESIGN.md system'), which is a step above a tautology, but 'apply' is ambiguous — an agent cannot tell whether this fetches/returns a design system, writes token CSS into a project, or scaffolds files. It does not clearly distinguish itself from the sibling aura_get_design_system, which likely retrieves the same artifact.

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?

There is no statement of when to use this tool versus aura_get_design_system, aura_search_design_systems, or aura_install_component. The only hint is 'copy order (tokens first, then markup)', which hints at an output sequencing convention but is not framed as a usage condition.

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