Vlak

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

Annotations already disclose readOnly, idempotent, and non-destructive behavior, so the description does not need to restate it. It adds the kebab-case naming convention and lists what the result contains, but that list is largely return-value information which the output schema already covers. No auth, error, or rate-limit behavior is described.

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: the first front-loads what the tool returns and the second is a crisp, actionable instruction. There is no redundant text or tautology, and both sentences earn their 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 single-parameter, read-only retrieval with an output schema and full annotations, the description is adequate. It explains the resource returned and the valid source of the parameter, though it stops short of describing behavior with invalid or nonexistent names.

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 documents 'name' with examples, so the baseline is 3. The description adds extra meaning by requiring the kebab-case format and directing the agent to use names from list_components or search_components, which provides provenance and format guidance beyond the schema.

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 (get the markdown docs page for a component) and enumerates the returned resource pieces: props JSON, CSS snippet, React example, classes, and aliases. This distinguishes it from siblings like list_components, search_components, and get_guide.

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 to pass the kebab-case name from list_components or search_components, which establishes a clear input source and implicitly says when to use this tool (once a specific component is known). It does not explicitly explain when to choose it over get_guide, get_install, or get_tokens, but the resource type is clear enough.

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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that – no note on whether pages are static, cached, or versioned – so a baseline 3 is appropriate.

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 mandatory default ('Read the general guide first') is front-loaded, and every clause in the enumeration maps a page value to its content, so nothing is filler. It is a single dense sentence, but the density is justified by the seven-way enum.

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 one optional parameter at 100% coverage and an output schema present, the description needs only to explain page selection, which it does for every enum value. Nothing critical is missing 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?

Schema description coverage is 100% and the enum values are already listed, so the baseline is 3. However, the description adds real semantic value by explaining what each enum value ('ios', 'ai-index', 'ai-parity', 'agents') actually contains, which the bare enum labels 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 opens with a specific verb+resource ('Read the general guide') and then maps each enum value to the content it returns (browser React components, AI catalog, runnable assistant, etc.), so the agent knows exactly what the tool surfaces. It stops short of naming or contrasting the sibling tools (get_install, get_tokens, get_component), so it is not quite a 5.

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 sequencing advice ('Read the general guide first') and describes what each page selection is for, effectively routing the agent among the enum options. There is no statement of when not to use this tool or which sibling to pick instead, which keeps it below a 5.

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 declare readOnly and idempotent behavior, so no contradiction. The description adds that it returns three installation methods plus CSS-only markup and registry dependencies, which is useful. However, it does not clarify whether installation is actually performed or just documented, and it omits details like error behavior or output format.

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?

One sentence packs in the key output details: three install methodsasi and CSS-only markup. It is concise and front-loaded, though the parenthetical list is slightly awkward and makes the sentence dense.

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-only tool with one parameter retriever, the description conveys the main output content (install methods and CSS-only markup with registry dependencies). It does not explicitly mention the return format or errors, but the read-only annotations and simple input reduce the need for more.

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 covers the single parameter 'name' with 'Component name', and the description references 'one component' without adding further semantics. The parameter meaning is fully documented by the schema, so the description provides little additional value.

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 title 'Get install commands' and description clearly identify the resource: install instructions for a component. It enumerates the three install methods and CSS-only markup, which distinguishes it from siblings like get_component or get_tokens. However, the description is a noun phrase without an explicit verb like 'Returns' or 'Gets,' so it is clear but not maximally explicit.

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 this tool is for retrieving install commands for a single component, but it does not explicitly state when to use it over alternatives like get_component or list_components. There is no direct comparison or exclusion guidance for sibling tools.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying exactly what data is exposed (light and dark values, StyleX aliases, raw groups), which helps set expectations beyond the empty parameter 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?

A single dense sentence front-loads the main subject and then lists the included categories with no filler. Every phrase adds information about what the tool returns.

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 zero parameters, a rich output schema, and comprehensive annotations, the description fully covers the invocation context. An agent knows exactly what this tool provides and can safely call it without additional guidance.

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 has zero parameters, so the description need not explain parameter meaning. The baseline of 4 applies; the description still adds value by clarifying the scope of the returned token data.

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 the specific resource (design tokens page) and enumerates its contents: CSS custom properties, light/dark values, StyleX aliases, and raw token groups. This clearly distinguishes it from sibling get_* tools like get_component and get_guide without needing to inspect schemas.

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 intended use is implied: call this when design tokens or CSS custom properties are needed. However, there is no explicit when-to-use guidance or mention of alternatives, even though similar siblings exist. The description makes the use case obvious but leaves routing 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 readOnlyHint, idempotentHint, non-destructive and non-open-world behavior, so the safety profile is covered. The description adds genuine scope context beyond that: authentication, authorization, storage and deployment are host responsibilities described by the manifest, telling the agent what this call will not do. It still says nothing about size limits, pagination, or whether source files are inlined or referenced.

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 tight sentences with zero filler. The primary action and return payload are front-loaded, and the scope disclaimers follow as supporting context.

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?

An output schema exists, so the description needn't enumerate return fields, and the annotations cover the safety profile. Combined with a 100%-covered parameter schema, the definition is nearly complete; only a cross-reference to sibling tools for related lookups 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?

The single 'id' parameter has 100% schema description coverage including an example, so the schema carries the semantics. The description reinforces that exactly one workflow is returned (hence a singular id), but adds no format, resolution, or lookup-detail beyond the schema; 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 uses a specific verb ('Return') and names the resource precisely ('one bundled workflow manifest and its source files'), which clearly contrasts with the plural listing sibling list_workflows. It does not, however, explicitly name or distinguish itself from get_component or get_guide, so differentiation is implied 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?

Usage is implied by the singular 'one bundled workflow' phrasing, which signals a single-item fetch by ID as opposed to the sibling list_workflows. There is no explicit when-to-use statement, no prerequisites, and no routing advice toward get_component or search_components for related lookups.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope (all components, filterable by category) and field coverage, but does not add behavioral details such as pagination, ordering, or response size.

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 a single efficient sentence with the core purpose front-loaded and the filter details following. The long category list is justified because the schema does not provide enums, though it makes the description slightly dense.

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-only list tool with one optional parameter, a rich output schema, and strong annotations, the description covers the key behavior and valid input values. It is not fully complete only because it does not address routing versus sibling 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?

The schema's category description is minimal ('Only this category'), while the description adds a concrete list of accepted category values. This materially helps an agent choose a valid category and understand what filtering means.

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 the tool lists every catalogue component with specific fields (name, title, description, category, aliases) and supports category filtering. This is a clear verb+resource definition, but it does not explicitly distinguish itself from sibling tools like search_components or get_component.

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 the tool is for browsing the full catalogue or filtering by category, giving clear context. However, it provides no guidance on when to use this instead of search_components for text-based lookups or get_component for a single 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 declare this as a safe, idempotent, non-destructive read, so the safety profile is covered. The description adds that results are "bundled" kits and recipes, which hints at curation, but says nothing about result volume, ordering, or truncation behavior. Modest added value beyond structured fields.

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 short sentences, front-loaded with the core action and followed by the query behavior. No filler, no repetition of the title or parameter names.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. What remains unexplained is result count/pagination behavior, which is minor for a single-optional-param listing 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?

Schema coverage is 100% and the schema only says "Optional workflow search." The description goes further by enumerating what the query actually matches (ID, title, description, components, adapters, states), which is genuinely useful semantics not present in the schema.

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 bundled workflow kits and recipes"), which clearly distinguishes a bulk-listing tool from the singular get_workflow sibling. However, it never explicitly names how it differs from list_components or get_workflow, leaving the agent to infer the boundary.

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 mention of an "optional query" implies the browse-vs-search usage pattern, but there is no explicit guidance on when to prefer this over get_workflow (single item) or list_components (a different resource family). Usage is implied 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 provide readOnly, idempotent, and non-destructive hints, so the behavior bar is lower. The description adds valuable normalization behavior: spacing, punctuation, and capitalization don't affect matching. It also discloses that results are ranked by field, which is beyond what the annotations or schema state.

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 core purpose, and follows with matching details and ranking behavior. The alias list adds specificity without bloat and every clause 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?

Given the small parameter surface, rich input-schema, output schema, and annotations, the description adequately completes the picture. It addresses the non-obvious matching semantics, though it doesn't mention potential null results or pagination behavior—minor gaps not essential to selecting the 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?

While the schema already covers 100% of the parameter, the description dramatically expands term semantics by revealing it can match aliases like shadcn/ui or common names, plus rs-* classes. This goes beyond the schema's simple examples and meaningfully improves correct invocation.

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 specific verb and resource, 'Find components', and goes on to enumerate the searchable fields (name, title, description, alias, rs-* class). This clearly differentiates it from sibling tools like get_component (exact fetch) or list_components (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 description gives a clear sense of what kinds of terms can be searched (fuzzy/alias/rs-*), so it implies usage for locating components without exact IDs. However, it never explicitly names when to prefer this over get_component or list_components, leaving alternative selection to inference.

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