Find a Design System for a UI Build

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely useful behavior the annotations cannot express: results are ranked matches with Preview links, scores should not be shown, the top ~4 should be presented as a question rather than auto-picked, and an existing selection should be retained rather than regenerated. Only the result-set size/shape is left loose (no output schema, no stated match limit), keeping this short of a 5.

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?

Roughly two-thirds of the text is not about this tool: the 'Open Slide' presentation mandate, the 'Explain design trade-offs' policy with its 'Gain: ...; lose: ...' template, and ecommerce color heuristics. These are workflow rules that belong in a guide tool, and they push the actual purpose statement to the bottom of the definition. Headers help navigation but do not fix the bloat for a one-parameter search.

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 read-only, single-parameter catalog search, everything an agent needs is present: when to call, what comes back (ranked matches with Preview links), what to do with the results (present top ~4, ask, then pass `baseDesignSystemId` downstream), and what not to do. No output schema exists, but the description explicitly characterizes the return payload well enough for correct invocation.

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?

The single `query` parameter is fully documented in the schema, so baseline 3 applies; the description goes further by giving a search taxonomy (industry, personality traits, natural-language UI description) plus a recommendation heuristic ('recommend by buyer, never by product material'). That taxonomy is meaningful guidance the schema's three examples do not convey.

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 does state a specific verb and resource — 'searching the catalog for relevant brand foundations and returning ranked matches with Preview links' — and distinguishes itself from create-design-system and generic coding/canvas tools. However, that statement appears near the end, after several sections about presentations and trade-off explanations, so the agent must read past unrelated content before understanding what this tool does.

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?

Explicit trigger conditions ('build/make me <app>', 'improve this form'), explicit exclusions ('Do not use this for backend-only work, data analysis, copywriting'), and an explicit ordering rule versus alternatives ('Call it before a generic coding, canvas, artifact, or site-building tool'). It also names the downstream alternative (create-design-system) and the handoff parameter, so there is no ambiguity about sequencing.

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