Wisty UI

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the safety profile is settled. The description adds real context beyond them: what sections exist, that `style` changes which API variant is returned, and that `source` inflates the response with files an agent rarely wants.

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?

Front-loaded with the verb and the returned content, which is the right order for a read tool with no output schema. The long inline enumeration of sections partly duplicates the schema enum and the phrase "its examples by name" is slightly opaque, but nothing is filler.

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 output schema, the description carries the burden of describing the return value, and it does so section by section, plus it explains the two optional parameters' trade-offs. Only the absence of sibling routing and of any size/token warning keeps it short of 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?

Schema coverage is 100%, so the parameters are already documented and the baseline is 3. The description adds marginal meaning — the "rarely need" steer away from `source` and the section-subset shortcut — but restates the `style` guidance the schema already gives.

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?

Uses a specific verb and resource ("Read one Wisty UI item") and then enumerates the payload it returns, so an agent knows exactly what comes back without an output schema. It never names or contrasts the sibling tools (search_components, list_components, get_example, get_install_command), so differentiation is only implicit.

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 offers useful in-tool guidance — narrowing via `sections` when the item is already known, and preferring the shadcn install command over `source: true`. However, it never states when to reach for this tool rather than search_components or list_components, leaving the sibling-routing decision to inference.

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 readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds real value beyond that by disclosing default resolution when "example" is omitted and the composition/ordering of returned content (page block examples include the files its install writes, imported files follow). It does not mention size limits or truncation of the returned code.

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?

Purpose is front-loaded in the first sentence with no wasted preamble. The middle sentences about page-block example composition are dense and grammatically tangled ("the files its install writes, the page first"), costing readability, though they are not padding.

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 output schema, the description does the necessary work of explaining what is returned (working example code, plus associated install/imported files) and what the optional parameters default to. The remaining gap is behavioral detail about response shape or size, which is minor for a read-only fetch.

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 all three parameters are already documented, including the "style" fallback to the Radix version. The description reinforces the "example" default behavior but adds no format or syntax detail beyond the schema, so the baseline 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?

"Get the code of one example of a Wisty UI item" gives a specific verb (get) and resource (an item's example code), and the closing mention of get_component clarifies the relationship between fetching one example versus listing them. It stops short of a crisp single-sentence statement of scope, but an agent can tell what it returns.

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?

"Without example, the first one, which shows the job the item is for" gives useful default-selection guidance, and the note that get_component lists examples by name implies a discovery workflow. However, there is no explicit when-to-use-this-vs-alternatives statement (e.g. when to call get_component or get_install_command instead), so routing is inferred rather than 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?

Annotations already declare read-only, idempotent, non-destructive, so safety is covered. The description adds the material behavioral fact that the tool returns a plan of steps rather than installing, that the theme write happens only once (tied to the themed flag), and that an icon-sprite copy step is conditionally included — real context beyond the annotations.

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 the verb and resource front-loaded and no filler. The first sentence is a long triple-clause construction that takes some parsing, but every clause conveys a distinct step type rather than restating the title.

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?

There is no output schema, so the description must explain what comes back — it does, enumerating the returned steps and their conditional variants. It also covers the init prerequisite and the once-only theme write, leaving nothing essential an agent needs before calling it.

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%, including where style and tailwindCss values come from in components.json, so the schema already carries the parameter burden. The description reinforces the components.json/src-dir provenance and ties the theme step to the themed condition, but adds little that the schema does not already say, and never mentions the required name parameter.

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: 'Get the steps to install one Wisty UI item with the shadcn CLI,' and enumerates what those steps contain (npx command, theme step, icon sprite copy). It does not name or contrast any sibling such as get_component or get_example, so an agent must infer the boundary itself.

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?

There is no explicit when-to-use versus alternatives statement; the reader must infer that this comes after search_components/list_components. The description does give a concrete precondition chain (read components.json and check for src/ first; run shadcn init when there is no src/), which is useful but procedural rather than selection 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is settled. The description adds behavior annotations don't: exactly what each item carries (name plus first sentence) and the four-way taxonomy that governs what comes back. Pagination and result-size behavior remain unstated.

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 listing behavior is front-loaded, then the taxonomy, then the alternative-tool routing, all in four short sentences with no filler. Every clause carries either scope, definition, or routing information.

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-parameter browse tool with no output schema and full annotation coverage, the description is complete enough to call correctly and interpret results. It stops short of describing item shape beyond name and first sentence, but nothing essential is missing.

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% with an enum on the single optional parameter, so the baseline would be 3. The description earns above baseline by defining what each enum value actually means — primitives are shadcn components with the Salesforce look, blocks are Salesforce assemblies, helpers turn records into block props — which the enum strings alone 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?

"List every Wisty UI item by kind, with its name and first sentence" gives a specific verb, resource, and even the shape of each returned entry. The following sentences define the four kinds, so an agent can distinguish this browse tool from get_component/search_components without opening a schema.

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?

"Prefer search_components when you know the job" supplies an explicit alternative plus the condition that selects it, implying this tool is the browse-when-you-don't-know path. It does not mention when to follow up with get_component/get_example, but the core routing decision is covered.

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 cover safety (readOnly, idempotent, non-destructive), so the description focuses on what it alone can add: results are ranked best-first, each match returns name, kind, description, and conditionally a When to use / When not to use line only when the docs contain the query words. That conditional field behavior is genuinely non-obvious and is exactly the kind of disclosure annotations cannot carry.

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 sentences, front-loaded with purpose and ranking, then the query constraint, then the return shape and next step. The third sentence is syntactically tangled ("the line of its When to use or When not to use that does"), costing a point on readability.

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?

There is no output schema, so the description carries the return-value burden and does: it names the returned fields and the conditional doc-line inclusion. Combined with query formulation guidance and the get_component handoff, an agent has everything needed to call and follow up correctly.

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%, so the baseline is 3; the description earns above that by giving worked query examples ("record picker", "picklist", "confirm delete") that show the intended keyword granularity, and by echoing the kind enumeration inline. It does not clarify limit behavior beyond the schema's default of 8.

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 ("Find Wisty UI components") plus the ranking behavior, and ties the search dimension to "the job they do" rather than names. That framing distinguishes it from list_components (enumerate) and get_component (read one item) named in the siblings.

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 prescribes query form ("one to three short keywords... not a sentence") with four concrete examples, and closes the loop with "Read a match with get_component." It does not say when to prefer list_components instead of keyword search, which is the remaining gap.

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