get_design_system

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description only needs to add behavior beyond that. It adds the default return shape (token categories and DTCG/CSS/flat formats), which is useful in the absence of an output schema, but it says nothing about behavior for unknown IDs, missing token groups, or the size of an unfiltered response.

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 front-loaded sentence with zero filler: the purpose is stated first, then all supporting detail is compressed into one clause. The token-category enumeration is slightly redundant with the group parameter schema, so it is not perfectly minimal, but every remaining word carries usable information.

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 simple read tool this is broadly sufficient: the schema documents all three parameters fully and annotations cover side-effects, while the description signals the default response shape (token groups and formats) despite there being no output schema. Notable gaps are the lack of guidance on discovering a design system ID, confirmation that all groups are returned by default, and any edge-case behavior for invalid IDs.

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 100%, so the baseline is 3: every parameter, including the format enum with defaults, is already documented in the schema. The description mostly restates those same values with slightly richer labeling ('W3C DTCG, CSS custom properties, or flat'), adding meaning but not compensating for any 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 opens with a specific verb-resource pairing: 'Get design tokens for a specific design system', and enumerates the token categories and output formats. 'Specific' plus 'design tokens' clearly distinguishes it from list_design_systems, get_brand_system, and list_design_system_components, though it does not name any sibling explicitly.

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?

Usage is only implied: the token categories and formats suggest this is for retrieving design token values for a chosen system. However, there are no explicit conditions, exclusions, or alternatives given — for instance, no pointer to list_design_systems for discovering valid IDs or to get_brand_system for non-token brand data — leaving routing decisions entirely to the agent.

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