List design themes

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

With no annotations, the description carries the full transparency burden. It discloses pagination behavior (total + next offset), that `use` re-orders rather than narrows, that summaries lack tokens/DESIGN.md/fonts, that fitness scores are computed with `reason` absent for all kits, and that the tool is read-only/free and lists Pro kits without exposing contents.

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 description is long but information-dense; every sentence contributes critical context such as catalog contents, filtering semantics, pagination, content absence, and alternatives. It is front-loaded with purpose and free of filler, though slightly verbose for a simple reader.

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 exists, so the description explains the response shape (compact summaries with fields, total + next offset) and explicitly lists what is absent. It covers filtering, pagination, content limitations, and alternative tools, making it complete for a tool with this complexity.

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 100%, but the description adds non-obvious behavioral semantics beyond parameter descriptions: `use` re-orders instead of narrowing, `q` is synonym-aware, pagination requires paging through offsets, and the fitness score caveat (read the order, not the number). It also explains how to interpret `charts` blocks for data lanes, which is actionable and beyond schema.

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?

Description opens with the specific verb and resource: 'Browse the published catalog as compact summaries,' and positions this as 'the main entry point for finding a design kit.' It also differentiates from siblings by directing token/DESIGN.md retrieval to get_design_md/get_tokens and naming search_themes as the alternative for subtle briefs.

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 states when to use: 'This is the main entry point for finding a design kit' and provides exclusions: 'Prefer search_themes when the brief is too subtle to rank against a lane.' It also advises using get_design_md or get_tokens for full contents, giving concrete alternatives.

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