tealmac UI

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that the output is a runnable shell command scoped to a project root, but says nothing about behavior for unknown item names, whether the command is versioned, or whether it assumes the CLI is installed.

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 sentences, front-loaded with the return value and followed by the one operational caveat. Nothing redundant, nothing padded.

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 read tool with no output schema, it does indicate the return type (a command string). However, it omits what the type parameter selects and how failures/unsupported items are surfaced, which an agent needs to use it confidently.

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%, so the description must carry parameter meaning. It covers packageManager well (npm/pnpm/yarn/bun) and implies name is the item identifier, but the six-value type enum (component, chart, block, template, pattern, hook) is never explained, leaving a third of the parameters opaque.

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 concrete verb and resource: it returns the exact shadcn CLI install command for an item, across four package managers. That clearly separates it from get_item (item data) and the list/search siblings, which never return shell commands.

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 tells the agent what to do with the result ("Run it in the project's root"), which is useful operational context. But it gives no when-to-use versus get_item, no prerequisites, and no exclusions, so selection guidance remains implied.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by enumerating the broad payload, including dependencies, accessibility notes, quality checks, registry JSON, and install command, though it does not mention not-found or name-collision behavior.

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 one front-loaded sentence with a colon-delimited list of returned content. It contains no filler, and every listed item contributes to what the agent can expect from the call.

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 two-parameter read tool with no output schema, the description enumerates the returned fields and the annotations cover safety and openness. Minor gaps around not-found handling and name-collision behavior remain, though the schema already documents the Pro-registry prefix convention.

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 fully documents both the required name and optional type enum. The description only echoes 'one item' and adds no parameter syntax or format details beyond what the schema already provides, so the baseline score of 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 a specific retrieval operation: all details for one named item, and it enumerates the returned content. It distinguishes 'one item' from list/search siblings, but does not explicitly name alternatives.

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 implies usage for fetching a single item's complete record, but gives no explicit when-to-use/when-not guidance or alternatives such as search_items or get_install_command. The intended context is inferable but not stated.

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?

The readOnlyHint already covers the safety profile. The description adds that the result includes each rule's rationale and how to meet it, which is useful content context, but it does not describe return structure, completeness, or ordering.

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 tightly written sentences with no waste. The content is front-loaded, and the usage instruction follows naturally.

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 zero-parameter, read-only rule lookup with no output schema, the description gives enough context about what is returned and why to call it. It could explicitly say whether all rule categories are returned in one call, but the gap is minor.

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 tool takes zero parameters, so there is no parameter semantics to explain. The baseline for zero-param tools 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 a specific resource: accessibility, motion, theming, and SSR rules that every item follows, including rationale and implementation guidance. This clearly distinguishes it from sibling item-listing and search tools.

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 explicit timing guidance: read before writing UI so the first draft passes. It does not name alternatives or when-not-to-use cases, but the primary usage context is clear.

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?

readOnlyHint=true and openWorldHint=false already establish that this is a safe, closed-world read, so the description carries a lighter burden. It adds that results include per-category counts, which is genuinely useful return-shape context, but says nothing about ordering, pagination, or whether counts are global or scoped.

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 sentences with no filler, and the operational instruction (use the category as a list_items filter) is placed last as a natural follow-on. The first sentence is slightly convoluted by stuffing six enumerations into a single clause, but nothing is wasted.

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?

With no parameters, no output schema, and only read-only annotations, an agent needs the return content and the follow-up usage — both are present. The only omission is the exact shape of the response (flat list vs. grouped object), which is minor for such a simple tool.

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 tool takes no parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a zero-parameter tool.

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 the concrete content returned — counts of components, charts, blocks, templates, patterns and hooks plus their category groupings — which is far more specific than the tautological title. It doesn't use an explicit verb like 'list' and doesn't contrast itself against get_item or search_items, but an agent can infer the resource from the enumeration.

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 final sentence gives a clear downstream-use rule: 'Use a category name as the filter of list_items.' That effectively tells the agent this is the discovery step preceding list_items, which is actionable routing. It stops short of explicit when-not-to-use or naming any alternative such as search_items.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no mention of result size, pagination/truncation, ordering, or what an unfiltered call returns, which matters for a 6-type catalog with no required params.

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?

A single front-loaded sentence with no filler. It is appropriately sized for the tool's simplicity, though the parenthetical cross-reference slightly interrupts the flow.

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 zero-required-param list tool with full schema coverage and no output schema, the description is minimally sufficient to call correctly. It leaves the agent guessing about volume, ordering, and whether unfiltered listing is safe/cheap — details that matter when no filter is required.

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% and the type enum is fully documented in the schema, including what each kind means. The description's only added value is the cross-reference that a category value must come from list_categories, which is a small but real clarification; 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?

States a specific verb and resource ('List items') plus the two available filter dimensions, so the agent knows this is a broad enumeration rather than a lookup. It does not, however, distinguish itself from the sibling search_items, which an agent could easily confuse with this.

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 phrase 'optionally filtered by category and type' implies when to use it, and the pointer that category names come from list_categories is a genuinely useful routing hint. There is no explicit when-not guidance or comparison to search_items/get_item.

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?

Annotations already establish read-only and closed-world behavior. The description adds meaningful behavioral context: common synonyms are understood, results are ranked as 'best matches,' and results include install commands. It does not cover ranking details or result limits, but it is strong for an annotated read-only search 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?

The description is three compact sentences with no wasted wording. The core search scope is front-loaded, followed by useful examples and a concise return-value 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 read-only search tool with no output schema, the description gives enough to call it correctly: what is searched, example queries, synonym behavior, and that install commands are returned. Minor gaps remain around result limits, ranking, and explicit routing versus sibling list/get tools.

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 67%, and the description adds useful query semantics through examples and synonym handling beyond the schema's bare 'What to find.' However, it does not explain the limit parameter or add much beyond the schema's detailed type enum 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 clearly states a specific verb and resource: search components, charts, blocks, templates, patterns, and hooks by need. It does not explicitly name or contrast with sibling tools such as list_items, so it is clear but lacks explicit sibling 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?

Usage is implied through phrases like 'by what you need' and examples such as 'date picker' and 'confirm before delete', suggesting semantic/keyword search. However, it does not explicitly say when to use this tool versus list_items or get_item, nor does it state exclusions.

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