list_tokens

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the 127/49 required-vs-optional split, the housekeeping fact that the per-component --radius-* tokens were removed, and the cascade pattern (--btn-radius: var(--radius-md)). It does not mention pagination or ordering semantics, which matters given limit/offset parameters.

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?

The purpose is front-loaded correctly, but the description then runs long with housekeeping and theming advice (spacing-scale guidance, removed-token notes) that reads more like migration documentation than list-tool guidance. Sentences earn their place individually, yet the density is high for a simple list operation.

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 list tool with no output schema and 25% schema coverage, the description supplies the missing shape information: total count, category vocabulary, and required/optional breakdown. It would be complete if it also covered pagination behavior and how it differs from search_tokens.

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 only 25%, so the description must compensate. It effectively documents the category parameter by enumerating all 17 category names, and explains the required/optional distinction that backs the 'required' boolean. The limit and offset parameters remain completely undocumented in both schema and description.

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 and resource ('List the CSS custom-property tokens in the theme contract') with concrete counts and a full category enumeration, so the agent knows exactly what comes back. It never distinguishes itself from the sibling search_tokens or get_token, which is the one thing an agent needs most when several token tools exist.

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 search_tokens, get_token, or get_token_map, all of which appear in the sibling list. The theming notes describe the token domain rather than when this specific listing call is the right choice.

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