NuvUI

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful payload context (files, dependencies, install command) since no output schema exists, but it omits any error behavior, size/limits, or what 'in full' entails.

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 tight sentence with no filler, leading directly with the resource. Slightly awkward phrasing ('the command that adds it to a project') costs it the top score, 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?

For a one-parameter idempotent read with no output schema, the description covers the return payload adequately but not fully: it doesn't say what happens on an unknown name, whether files are paged or truncated, or how the install command should be used. The annotations carry the safety story, leaving the description minimally sufficient.

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 there is a single parameter, so the schema fully documents 'name' including its pattern and the example 'sign-in'. The description adds nothing about the parameter, which is the expected baseline when the schema does the work.

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?

Names the specific resource (a block) and enumerates what is retrieved: its files, the packages they require, and the install command. An agent can tell it fetches one block's detail. It falls short of 5 because it is phrased as a noun fragment with no verb and never distinguishes itself from get_chart/get_page/get_rules or explains its relationship to list_blocks.

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, when-not-to-use, or alternative tool named. The only usage signal is implied: the tool reads a single block by name. The schema hints 'name from list_blocks', but that routing guidance lives in the parameter, not the description.

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 title 'Read a chart', so the safety profile is fully covered. The description adds 'in full', usefully signaling complete file content rather than a summary, but says nothing about return format or errors.

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 short sentence with no filler, and the key qualifier 'in full' is front-loaded. It reads as a fragment rather than a sentence, which slightly hurts clarity but keeps the definition tight.

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 fully-documented parameter, complete safety annotations, and no output schema, relatively little is required. Still, the description never characterizes what the returned 'file' contains or how a chart type like bar/stacked maps to a file, leaving a modest gap.

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%; the parameter is documented as 'A chart's id from list_charts, such as bar/stacked.' The description largely restates this same information, adding no format or syntax detail 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 fragment 'A chart's file in full' conveys the resource (a chart) and implies full retrieval, but the verb is implicit and the phrasing is grammatically incomplete. Naming 'from list_charts' gives sibling context, though it does not clearly distinguish this from the other get_* tools beyond the resource.

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 only usage signal is the phrase 'from list_charts', which hints that chart identifiers come from that tool. There is no statement of when to use this versus list_charts (summary vs full) or any prerequisite/exclusion 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 readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety is covered. The description adds return-format context the annotations cannot: output is Markdown and 'One page' (implying bounded, non-paginated output), plus the effect of section narrowing the response to a single part.

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 dense sentences, front-loaded with what is returned, then how to obtain the page value, then the section modifier. No filler or restatement of the tool name.

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 correctly carries the burden of describing the return shape (Markdown page content) and the section-narrowing behavior. It does not address output size limits or failure behavior for an invalid id, which are the only remaining gaps for a two-parameter read 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 description coverage is 100%, so the baseline is 3, but the description adds genuinely new meaning: it names the three tools that produce valid page ids and gives concrete examples (Compare, DataTable for page; Props, CSS variables for section). This goes beyond the schema's generic 'id or component name' phrasing.

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 ('One page of the reference, as Markdown') and enumerates exactly what that page contains (parts, props, examples, CSS variables, classes, accessibility, or a guide). It is clearly separable from the sibling get_block/get_chart/get_rules/get_tokens resources and from the list_* discovery tools it consumes ids from.

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 routes the agent to list_components, list_guides, or search_docs for the id, and explains the section parameter as a way to narrow to one part of a page. It stops short of stating when not to use this tool (e.g. bulk retrieval vs search_docs), so it is clear context without exclusions.

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 the safety profile (readOnlyHint=true, openWorldHint=false, idempotentHint=true), so the burden is lower. The description still adds real value by disclosing the two response shapes — an overview without a topic versus the full rule with wrong/right code examples with one — which is precisely the output-varying behavior an agent needs to know and could not derive from 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?

Front-loaded with 'Start here,' then two tight clauses mapping the no-topic and with-topic paths. Every sentence earns its place with zero filler, and the branch structure mirrors the single optional parameter.

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-optional-parameter, read-only docs tool with no output schema, the description fully specifies both invocation modes and what each returns. Nothing an agent needs to call it correctly 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% and the enum is described, so the baseline is 3, but the description goes further by explaining the semantic effect of supplying the topic parameter versus omitting it. It does not explain that only the listed topic values are valid, though the schema covers that.

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 communicates a specific resource (the nuvui rules/guidance) and frames itself as the entry point with 'Start here.' However, it never states an explicit retrieval verb, so the agent must infer that calling this returns documentation content. It is clearly distinguishable from get_block/get_tokens/list_components, but the differentiation comes from the 'start here' framing rather than an explicit scope statement.

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?

Strong conditional guidance: 'Without a topic' vs 'With a topic' tells the agent exactly what each invocation mode returns, and 'Start here' signals this is the first tool to call. It stops short of naming alternatives or when-not-to-use conditions (e.g., whether to prefer list_guides or list_components for specific 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, idempotentHint, and a closed world, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the return shape is CSS custom properties (var(--color-primary)) and the prefix argument narrows the result set. It stops short of noting ordering or result size, so not a 5.

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 core purpose front-loaded and the parameter behavior second. The clause 'never a color written out' is slightly idiomatic but still earns its place as a usage directive.

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 read tool with no output schema, the description supplies the two things an agent needs: the output format and the filtering behavior. Only minor gaps remain (behavior with no prefix, result ordering), which are low-stakes here.

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 0%, so the description must carry the parameter, and it does: the prefix argument 'gives only those' and the examples (--color-, --radius-, --text-) show the expected literal form including the trailing hyphen. That is meaningful guidance the bare schema pattern does not convey, though it doesn't clarify whether matching is a raw string prefix or a semantic group.

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 resource precisely ('The design tokens as CSS custom properties') and the annotation title supplies the read verb, so the agent knows it retrieves design tokens. It is clearly distinguishable from the sibling set (blocks, charts, pages, rules, components), none of which return tokens.

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?

'For your own CSS: var(--color-primary), never a color written out' gives the intended use case — pulling token names to reference instead of hardcoding colors. However, it never states when to call it versus any alternative, nor what happens when the prefix is omitted (presumably all tokens), so usage is only 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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context by explaining that each block is a TSX file and an SCSS file meant to be copied and changed, which tells the agent what to expect from the results. It does not describe pagination or listing limits, but with annotations and a simple schema this is a minor gap.

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 two sentences with no wasted words: the first explains what blocks are, and the second gives a clear usage directive. It is appropriately sized for a simple listing tool and front-loads the conceptual framing before the action cue.

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 low complexity, read-only annotations, and full schema coverage, the description is nearly complete. It explains what blocks are and when to use the tool, so an agent can invoke it correctly. The only missing detail is an explicit statement that it lists all blocks and optionally filters by category, but the schema covers the filter.

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 only parameter (category) is fully documented with its allowed values in the schema itself. The description does not add any additional meaning about the category parameter, such as filtering behavior or default scope, 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?

The description defines what blocks are and signals a discovery use case, making it clear this tool is for finding pre-built screens/parts. However, it does not explicitly state that it lists blocks or that it can filter by category, relying on the tool name and title for the exact action. It distinguishes itself from siblings like get_block by focusing on browsing available blocks rather than retrieving one.

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 clear context for when to use the tool: 'Look here before building a screen from nothing.' This is a strong, actionable usage cue. It does not mention when not to use it or explicitly point to alternative tools like list_components or search_docs, so it falls short of 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 already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the burden is lighter. The phrase 'each one file to copy' adds useful context that the result is copyable source, but nothing is said about filtering behavior, result size, or pagination.

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 tight sentence with no wasted words, and the resource identification is front-loaded. It is slightly under-specified rather than over-long, which is the better failure mode.

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 list tool with annotations covering safety and no output schema, most of what an agent needs is present, but the description omits what a listing returns and how the optional family filter behaves. The trailing 'and more' is also vaguer than the schema's explicit value list.

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 'family' parameter and its allowed values are fully documented in the schema. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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 identifies the resource (Recharts-based chart components from @nuvui/charts) and hints at the payoff ('each one file to copy'), but never states the verb 'list' or that it returns a catalog. Against siblings like list_components and list_guides there is no differentiation, so an agent cannot tell these apart from the description alone.

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 call this versus alternatives. The obvious sibling get_chart (fetch a single chart) is never mentioned, nor is the family-scoping behavior explained as a selection criterion. The agent gets no routing help.

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 and a closed world, so the safety profile is covered. The description usefully adds that the return content includes a one-line purpose per component (relevant because there is no output schema), but says nothing about result volume or pagination.

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 scope (every component page) front-loaded before the optional filtering behavior. No filler and nothing that could be trimmed without losing 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 single-param, read-only list tool whose annotations and schema are fully populated, the description covers what is returned and how to narrow it. The only shortfall is the absence of any routing cue toward sibling list/search 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 description coverage is 100% and the package param already enumerates valid values, so the schema carries the detail. The description only restates the filter's effect, adding no syntax or format meaning 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?

States a specific resource (component pages) and organizing dimension (by package), plus that each entry includes a one-line purpose. It reads distinctly from list_blocks/list_charts/list_guides, but never explicitly contrasts itself with search_docs or get_page, which are the likely alternatives for the same audience.

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?

"Pass a package to see only its pages" documents the filtering behavior, which implies when to supply the optional param. However, there is no guidance on when to use this list versus search_docs or get_page, so the when-not-to-use case is left 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, and openWorldHint=false, so the safety and determinism profile is fully covered. The description's only added behavior is the content taxonomy of what guides exist, with nothing about count, pagination, or what a returned entry looks like.

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 sentence that front-loads the defining characteristic ('the pages that aren't about one component') before the topic enumeration. The long list of topics is information-dense but borders on padding for a listing tool.

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?

No output schema, zero parameters, and annotations covering the safety profile, so the description's job is mainly to define scope, which it does well by enumerating the guide categories. It could note that it returns a flat list of pages, but nothing essential for correct invocation 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 tool takes no parameters (parameter count 0, 100% schema coverage), so the description carries no parameter burden. Baseline for a zero-parameter tool is 4.

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 identifies the resource precisely as the non-component doc pages (guides), and the enumerated topics make the scope unmistakable. It doesn't name a verb like 'list' nor explicitly contrast with siblings such as get_page or search_docs, so it falls short of 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?

Usage is implied by the contrast 'the pages that aren't about one component' and the 0-param, no-argument shape, which signals a browse-everything-index tool. However, there is no explicit when-to-use statement or routing rule pointing to search_docs or get_page for other needs.

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 readOnly/idempotent/closed-world, so the bar is lower, and the description adds value annotations can't carry: results are sections (not full pages), relevance-ranked, and each names its page and section. It still says nothing about the default limit, ranking quality, or what an empty result looks like.

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; the query examples and the pointer to get_page each earn their place by disambiguating input style and next step. No 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 correctly steps in to describe the result shape (page + section per hit). It leaves the limit/pagination behavior unexplained, which is the only real gap for a two-parameter search 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 0%, so the description must compensate. The worked examples ('sortable table', 'dark mode', 'error message on a field') do teach the query parameter that it accepts short keyword phrases or error text, but the limit parameter (default 8, max 20) is completely undocumented in either place.

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 — it finds reference sections that answer a question — and explicitly contrasts with the get_* siblings by framing itself as the search entry point whose results feed into get_page. An agent can tell it apart from get_page/list_* without opening any 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?

Gives clear context for when to reach for it (a question or a few keywords) and names the downstream tool to call with the results. It stops short of naming an alternative or a when-not-to-use condition, so it is clear context rather than full routing guidance.

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