find_design_systems

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

With no annotations, the description carries the full behavioral burden and does not say whether the tool is read-only, whether source_id is required to obtain technology tags, what the result list looks like, or how max_results interacts with filtering. The phrase "source-published technology tag" is the only behavioral hint, implying tag vocabularies originate from a catalog, but an agent still has to guess at the semantics of a fallback path.

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?

Two compact sentences that lead with the core capability and place the caveat last. Nothing is redundant, though the second sentence's drafting ("Existing query-only technology calls are supported as a documented fallback") is dense and takes effort to parse for what is a simple backward-compatibility note.

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 tool with no annotations, no output schema, and zero parameter documentation, the description is too thin: it omits the role of source_id and max_results, the shape of returned matches, and any statement of read-only safety. The backward-compatibility note is documented but leaves the agent uncertain what the primary calling convention should be.

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 0% across four parameters, so the description must compensate and largely fails: 'query' is described as name search and 'technology' is loosely explained, but 'source_id' (which clearly scopes the technology vocabulary) and 'max_results' (bounded 1-20, default 10) are not addressed at all. The fallback sentence hints at an interaction between query and technology but never clarifies how the parameters combine.

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 specific verb and resource ("Search design-system names") and distinguishes the primary query path from the optional technology filter, which differentiates it from component-level siblings like find_components. It stops short of a crisp statement about what a design system record is, and the trailing fallback sentence muddies rather than sharpens the purpose.

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?

No guidance on when to pick this tool over siblings such as find_components or compare_implementations; the only usage context is the note that query-only calls with a technology value are a "documented fallback," which signals legacy support but doesn't tell an agent which path to prefer or why. There are no exclusions, prerequisites, or example queries.

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