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

With no annotations, the description carries the burden and does useful work: it discloses that the tool ONLY returns a text snippet and requires the agent to edit or add files afterward. This is important behavioral context beyond the schema.

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?

Three short sentences: trigger, output scope, and follow-up action. Each sentence earns its place and the most decision-relevant information is front-loaded.

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 builder with no output schema or annotations, it explains what the tool returns and the required integration step. It lacks explicit sibling exclusions and return-shape detail, but the schema covers parameters and the trigger guidance is sufficient for selection.

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 schema already documents all five parameters. The description does not repeat parameter details but also does not add meaning beyond the schema, which is the expected baseline.

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 clear verb+resource: building new UI components, with concrete examples such as button, input, dialog, and form. It is clear about what the tool does but does not explicitly differentiate it from sibling tools like 21st_magic_component_inspiration or 21st_magic_component_refiner.

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?

It gives an explicit 'use this tool when' trigger and lists example request patterns. It does not spell out when to prefer the inspiration or refiner siblings, so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the behavioral disclosure burden. It states that no code is generated, that only the text snippet is returned, and that the agent must edit or add files afterward. It does not cover authentication, limits, or exact return shape, but the key behavioral constraints are disclosed.

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 short and front-loaded with the trigger conditions. There is some redundancy between 'returns the JSON data' and 'ONLY returns the text snippet', but the overall structure is efficient and the post-call instruction earns its place.

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 two-parameter fetch-like tool with a rich schema and no output schema, this description provides sufficient context: when to use it, what it returns, what it does not do, and what the agent must do afterward. It could be slightly richer on output formatting, but it is largely complete.

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 input schema already documents both required parameters with 100% coverage, so the description adds limited semantic value beyond the schema. The description clarifies that searchQuery is for finding a matching UI component, but this is also reflected in the schema's parameter 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?

The description clearly identifies the action as fetching component data and previews from 21st.dev, and it contrasts itself with code generation by stating it does not generate new code. It does not explicitly distinguish itself from the refiner sibling, so it stops short of full differentiation.

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?

The description opens with explicit trigger conditions: 'when the user wants to see component, get inspiration, or /21st'. It does not provide when-not guidance or name alternative tools, but the usage context is clear enough for an agent to select this tool appropriately.

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

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

With no annotations, the description carries the full disclosure burden. It does state the core outcome—'returns redesigned version of the component and instructions on how to implement it'—which implies a read/return behavior rather than a direct write. However, it never says whether the file at absolutePathToRefiningFile is modified, what happens on failure, or any prerequisites, leaving the side-effect profile unclear for a mutating-looking tool.

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 with the trigger condition front-loaded in the opening clause ('Use this tool when...'). There is minor redundancy—'improves UI' appears in both sentences—but no filler or irrelevant content.

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?

The definition covers what the tool does, when to use it, and the outcome, and the schema fully documents parameters. But with no output schema and no annotations, the concrete return format of the 'redesigned version and instructions' is unspecified, and side effects on the target file are unstated, leaving the full invocation contract incomplete.

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%, and the schema already documents all three parameters in detail—'context' even includes extraction rules and the 'return an empty string' fallback. The description text adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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 states specific verbs ('re-design/refine/improve') and a clear resource ('current UI component', 'React component or molecule'), and scopes the tool by excluding big pages. The outcome is also specified: it 'returns redesigned version of the component and instructions on how to implement it.' It does not explicitly distinguish itself from sibling tools (inspiration, builder), so differentiation is inferable rather than stated.

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 are given ('when the user requests to re-design/refine/improve current UI component with /ui or /21 commands, or when context is about improving, or refining UI for a React component or molecule') plus a clear exclusion ('NOT for big pages'). It stops short of naming alternatives—an agent is not told to use builder for new components or inspiration for ideas—so the when-not guidance is partial.

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

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

With no annotations to lean on, the description carries the behavioral burden and does well by detailing supported formats, theme variations ('if available'), and the exact structure of results (component name, code, import instructions). It does not cover failure modes or no-result behavior, but the disclosed behavior is sufficient for the agent to anticipate what will happen.

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 well-organized with clear sections for purpose, usage, examples, formats, and output structure. It is slightly longer than strictly necessary because example queries partially repeat the usage triggers, but each section earns its place and the key info is front-loaded in the first sentence.

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?

Given there is no output schema and no annotations, the description does a good job of explaining what the tool returns, including output format options and result fields. However, it mentions 'category filtering' even though the input schema has no category parameter, and it does not explain what happens when a logo is not found, leaving minor but real gaps.

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 schema already describes both parameters (format and queries), so the baseline is 3; the description adds significant value by defining what each format returns (TSX/JSX/SVG), providing concrete example query arrays, and showing how command-style inputs map to the queries parameter. This goes beyond the schema's minimal descriptions.

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 precise verb and resource: 'Search and return logos in specified format (JSX, TSX, SVG).' It clearly distinguishes itself from sibling tools (which concern component inspiration, refining, and building) by focusing on logo lookup and output formats. The example queries and command styles reinforce exactly what the 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?

The 'When to use this tool' section explicitly lists two concrete trigger conditions: user types '/logo' command or asks to add a company logo not in the local project. The phrase 'that's not in the local project' provides a clear when-not-to-use condition, effectively excluding cases where the logo is already available locally.

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