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

With no annotations, the description carries the full burden; it usefully discloses that the output is a ready-to-paste context block destined for an LLM, which is the key behavioral trait. It does not address invalid-intent handling, size/truncation behavior, or how multiple slices are composed.

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, front-loaded with the purpose and immediately followed by the parameterization details; every clause earns its place with no 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?

For a composite text-producing tool with no output schema and no annotations, the description identifies the purpose and all intent variants but leaves the returned block's shape, slice composition, and failure modes unstated. Adequate to invoke, not 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 baseline is 3, but the description adds real value by fully enumerating the valid intent values and the '<name>' parameterization syntax (mixin:, component:, theme:, recipe:), effectively compensating for the absent enum constraint 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 (Build) and resource (a ready-to-paste context block for an LLM consuming cia), and the intent enumeration conveys that this tool aggregates slices rather than fetching single items. It is clearly an assembly/composition tool, distinct from the many list_/get_/search_ siblings, though it never names an alternative to differentiate itself explicitly.

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 'Intent picks the slice' plus the enumerated intent values give clear guidance on how to parameterize a call, but there is no when-to-use/when-not guidance and no explicit comparison to the get_/list_/search_ siblings that fetch the same underlying data piecemeal.

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?

There are no annotations, so the description carries the full behavioral burden. It discloses what is returned (keyframe mapping with usage examples, or a mixin record), which is genuinely useful, but omits any error/missing-name behavior or other operational traits.

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 efficient sentence, front-loaded with the verb and return payload. It is dense but wastes little, though the dual-mode phrasing reads slightly awkwardly.

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 usefully explains the return shape (keyframe mapping plus usage examples, or a mixin record). This covers the main gap for a one-parameter lookup, though overlapping behavior with get_mixin remains unaddressed.

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 single `name` parameter is already fully documented in the schema. The description restates the slug-or-mixin-name duality without adding syntax or format detail beyond the schema, so the baseline 3 holds.

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 ("Return") and the resource it retrieves (an animation slug→keyframe mapping with usage examples). It clarifies the dual lookup mode (slug or mixin name), but does not differentiate from siblings like get_mixin, which it partially overlaps with by also returning mixin records.

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?

Implies usage by describing the two lookup modes (animation slug vs. mixin name), giving some context for when the tool applies. However, it names no alternatives and gives no when-not guidance, leaving the get_mixin vs. get_animation boundary ambiguous.

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?

No annotations are provided, so the description carries the full burden. It does disclose the return payload (description, public mixins with signature/summary/body, source path), which is genuinely useful context, but it says nothing about failure behavior for unknown names, lookup exactness, or cost of returning full bodies.

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, front-loaded with the action and payload list, with zero filler. Nothing is padded or repeated.

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 and no annotations, the description usefully enumerates what is returned, which is the main thing an agent needs here. It falls short only on not-found behavior and lookup matching rules, which are minor for a one-parameter getter.

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% for the single required 'name' parameter, and the schema already supplies examples ('buttons', 'overlay', 'forms'). The description adds nothing beyond it, which is the correct 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?

A specific verb-plus-resource: 'Return one component' with an enumerated payload. The word 'one' implicitly separates it from list_components and search_components, but it never names those siblings, so the differentiation is by inference rather than 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?

Usage is only implied by the singular 'one component' versus the sibling list_components/search_components. There is no explicit when-to-use or when-not-to-use guidance, and no statement of what to do when the name is unknown.

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?

No annotations are provided, so the description carries the full disclosure burden. It does useful work by revealing the payload shape (body and source location are included, so the caller should expect full source text), but it says nothing about failure behavior when a name is not found, ambiguity handling, or whether results are cached/versioned.

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 that names the operation and then lists the return fields with zero filler. Nothing is repeated from the schema or the 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 present, the description correctly compensates by enumerating the returned fields. For a one-parameter, fully documented read tool this is nearly sufficient; only error/not-found behavior is left unaddressed.

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 itself supplies the format expectation plus concrete name examples ('color', 'space', 'radius', 'shadow'). The description adds no additional semantics (no exact-match vs fuzzy behavior, no qualified-name syntax), 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?

States a specific verb ('Return one function') and resource, and enumerates exactly what comes back: signature, parameters, doc, body, source location. The singular 'one function' plus the get_/list_/search_ sibling naming pattern makes it distinguishable from list_functions and search_functions, though it never names those siblings explicitly.

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 only implied: the required 'name' parameter and the single-result framing suggest fetching a known function by name, leaving list_functions/search_functions for discovery. There is no explicit when-to-use or when-not-to-use statement, and no mention of how to find a name in the first place.

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 burden, and it does disclose the retrieval surface (signature, parameter list, doc comment, body, source path and line range), which tells the agent this is a read-only single-item lookup. It says nothing about error behavior for missing names, or whether the full body is always returned regardless of 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?

One compact sentence, front-loaded with the action and resource, then a tight enumeration of return fields. No filler and nothing that fails to earn 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?

With no output schema, the description must convey return shape and it does so explicitly, which is exactly the gap it should fill for a single-fetch tool. Only the error path for a non-existent mixin is left unaddressed, a minor omission for a simple read.

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 single 'name' parameter is documented in the schema with concrete examples ('btn', 'card'). The description adds no syntax or format detail beyond that, 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?

States a specific verb and resource ('Return one mixin') and enumerates the payload that comes back, so an agent knows this is a single-record fetch. The singular scope implicitly distinguishes it from list_mixins and search_mixins, though no sibling is named explicitly.

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 only implied by the get/list/search naming convention shared across the sibling set; the description never says when to reach for this over search_mixins or list_mixins, nor what happens for an unknown name. The minimum viable context is present but nothing is stated outright.

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 disclosure burden and does add real value by documenting the returned shape, including the two recipe kinds ("md" pattern vs "scss" import) and the differing body format for each. It omits error behavior for a missing slug, any size limits, and whether the body is returned verbatim or processed.

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; the verb and resource come first and the field enumeration follows. The parenthetical clarifications of body format are dense but each 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?

Since no output schema exists, the description must describe the return value, and it does so field-by-field including the kind-dependent body format and the category/complexity pair. Only missing pieces are failure modes and whether the recipe is the full unabridged body.

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 singular `name` is documented there with example slugs ("print-to-pdf", "combobox"), so the schema does the heavy lifting. The description contributes no additional parameter meaning beyond implying a single recipe is selected, which is the expected baseline of 3.

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 one recipe") and enumerates what that recipe contains (name, kind, category/complexity, usage, body), which is far more concrete than a tautology. It implicitly distinguishes itself from list_recipes/search_recipes by scoping to a single recipe, though it never names those siblings explicitly.

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 get_X naming convention against siblings like list_recipes and search_recipes: fetch one fully-resolved recipe by slug rather than enumerating or searching. However, there is no explicit statement of when to prefer this over list_recipes, nor any note on what happens for an unknown slug, so guidance remains inferential.

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 burden, and it largely does: it discloses the returned fields and adds a real behavioral constraint, 'Never hand-write the selector,' plus the effect of $standalone: false on the emitted :root. It does not state failure behavior for an unknown theme name or confirm freshness/caching, which keeps it short of 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?

Three sentences, front-loaded with the return payload, then the authoring constraint. The @mixin signature detail is arguably closer to get_mixin's territory, but it directly explains how $standalone shapes the output, so it mostly 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?

There is no output schema, so the description must describe return values, and it names all four returned components. For a single-parameter read tool that is complete enough for an agent to call it 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 description coverage is 100%; the name parameter is documented in-schema with concrete examples ('boilerplate', 'terminal', 'press', 'sketchbook-dark'). The description adds no naming syntax or validation rules beyond that, 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?

States a specific verb ('Return one theme') and enumerates exactly what comes back: token assignments, raw SCSS body, light-dark() support flag, and source path. That payload signature distinguishes it immediately from list_themes and search_themes, which return collections.

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 only implied: 'Return one theme' plus a required name parameter makes retrieval of a single theme self-evident, and the authoring note hints at when $standalone matters. However, it never explicitly says to use this instead of list_themes/search_themes when looking for a single known theme, nor what happens if the name does not exist.

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 and no output schema, the description carries the full disclosure burden and does well: it names the category, required flag, cross-theme sample values, and referencing mixins/functions. It does not mention permissions or side effects, but for a read-style lookup the disclosed return shape is genuinely informative.

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 that communicates the retrieval action and the returned payload with no filler or redundancy.

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 lookup tool with no annotations or output schema, the description adequately covers both the operation and the return contents. Only the behavior on an unknown name is unaddressed, a minor 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 coverage is 100% and the schema already explains the name parameter including the optional leading '--'. The description adds no additional parameter guidance, 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?

States a specific verb (Return) and resource (one token), and enumerates the returned fields. It clearly reads as single-item retrieval by name, though it does not explicitly contrast itself with list_tokens/search_tokens 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?

The singular 'one token' implies fetching a specific token rather than listing or searching, and the sibling names make the get/search/list distinction inferable. However, there is no explicit when-to-use or when-not-to-use statement and no alternative named.

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?

No annotations are provided, so the description carries the full burden. It does disclose what the tool returns (vocabulary, speed keys, effects, mixin signatures), which is useful behavioral context. But it doesn't clarify whether this is a static reference dump, whether results are paginated, or whether authentication is needed. For a zero-param list tool with no annotations, this is adequate but incomplete.

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 verb and then enumerates the four content categories. Well-structured with no padding. The parenthetical examples (fade-in, slide-up, etc.) are helpful but make it slightly longer than strictly necessary, though they earn their place by clarifying what 'vocabulary' means.

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 description is complete enough for the immediate call, but for a reference-discovery tool in a large ecosystem (34 siblings), it doesn't explain how this relates to get_animation or whether the output is a flat list or grouped structure. With no output schema and no annotations, and the tool being purely a listing utility, the description is minimally viable but leaves gaps around return format and relationship to singular-retrieval sibling.

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?

Parameter count is 0, giving a baseline of 4 per the scoring rules. The description adds no parameter information because there are none to document, and the schema is empty. The tool takes no arguments, so there's nothing for the description to compensate for.

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 verb (List) and enumerates the resource contents precisely: animation vocabulary, speed keys, animate-on effects, and mixin signatures. This clearly distinguishes it from siblings like get_animation (singular retrieval) and search_animations would, though there's no explicit sibling routing 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?

The list format implies this is a discovery/enumeration tool, and the enumeration of content categories hints at what it returns. However, there is no explicit when-to-use guidance, no mention of alternatives (e.g., get_animation for detail), and no exclusions stated. Usage is implied by the content listing 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?

No annotations are provided, so the description carries the burden, but this is a zero-parameter read-only list so the risk surface is small. It discloses scope (everything under a specific path, organized by the enumerated categories) yet says nothing about the return shape (names vs paths vs file contents) or any 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?

A single front-loaded sentence with no filler; the parenthetical category list is the only elaboration and it directly helps the agent predict the output.

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 trivial no-arg listing tool with no annotations or output schema, the description covers what is returned and its scope. The only real gap is the result format (filenames, paths, or contents), which is minor given the tool's simplicity.

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 the baseline per the rubric is 4. There is nothing for the description to disambiguate, and the parenthetical category list usefully describes the implicit partitioning of results.

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 ('List') plus the exact resource scope ('every component file under scss/components/') and enumerates the category subfolders, so an agent knows precisely what comes back. It doesn't explicitly contrast itself with get_component or search_components, but 'every' signals exhaustive enumeration versus the retrieval/search 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?

Usage is only implied: an agent can infer this is the tool for enumerating all components rather than fetching or searching one. There is no explicit when-to-use statement, no exclusion ('don't use this to find a specific component'), and no pointer to search_components/get_component as alternatives.

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 behavioral burden. It usefully discloses that a fixed, bounded set of 26 public items exists and that results mirror list_mixins' shape, but says nothing about pagination behavior despite limit/offset parameters, nor about ordering or auth needs.

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 packed sentences, zero filler. The resource and scope come first, and the shape comparison to a sibling is a compact way to convey format.

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 and no annotations, so the description must stand alone. It does convey the item count and output shape, but leaves three pagination/filter parameters entirely unexplained, which is a real gap for a 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 description coverage is 0%, so the description must compensate for limit, offset, and category. It only hints at categories (color, space, radius, shadow, font-size, z) without connecting them to the category parameter, and never explains limit/offset semantics.

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 (List) and resource (@functions), and adds concrete scope: 26 public functions with example categories. However, it never distinguishes itself from the sibling search_functions, leaving the list-vs-search split for the agent to infer.

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 explicit when-to-use guidance or alternatives are named. The implicit contrast between 'List all' and the sibling search_functions can be guessed from the names, but the description itself provides no routing instruction or prerequisites.

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?

No annotations are provided, so the description carries the full disclosure burden. It usefully says the mixins are public and gives the total count and source categories, but it does not describe pagination behavior, response format, or how limit and offset interact with the listing.

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. The count, scope, and available filters are front-loaded with no filler, and both sentences directly help an agent decide whether and how to call the 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?

For a list tool with four parameters, no annotations, no output schema, and low schema coverage, the description provides enough to understand the resource and primary filters. It is incomplete regarding pagination semantics and the returned structure, which an agent may need in order to call it 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 description coverage is only 25%, so the description should compensate. It does add meaningful semantics for category by enumerating allowed values (core/layout/animation/icons/generator/component/recipe) that are absent from the schema, and it restates component filtering. It leaves limit and offset unexplained.

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 (List) and resource (@mixins), with the exact scope of 157 public mixins and their source categories. It is clearly distinguishable from get_mixin and search_mixins in practice, though it does not explicitly name those siblings as 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 by noting that results can be filtered by category or component name, which tells an agent how to narrow the list. However, it gives no explicit when-to-use guidance, no exclusions, and does not point to search_mixins as a text-search alternative.

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 present, the description carries the full behavioral burden. It does add real context about the returned content — the two kinds, their attribute sets (category, complexity), and the @use consumption model — which is more than a bare listing. However, it never states that this is a read-only operation, whether results are paginated or filtered, or what happens on failure.

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 compact sentence with a parenthetical, with the source location front-loaded and the two kinds broken out cleanly. It is dense but every clause conveys distinct information about what recipes are and how they differ.

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 exists, so the description must convey return-value shape, and it does so reasonably: it names the two kinds, the kind discriminator, and attributes such as category and complexity. A few result fields and any ordering/pagination behavior remain undisclosed, but this is largely complete for a zero-parameter 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description's discussion of the kind field describes output shape rather than input, which is useful but belongs under return-value disclosure.

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 recipes from scss/recipes/') and goes further by defining the two content kinds with their discriminator values (kind:"md" vs kind:"scss"). It does not explicitly contrast itself with the sibling get_recipe, but the list/get distinction plus the enumerated kinds makes the tool's scope unambiguous.

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 rather than stated: an agent can infer this is the discovery entry point for recipes before calling get_recipe, and the kind explanations hint at when each category matters. There is no explicit when-to-use, no named alternative, and no prerequisites, so it stays at the minimum-viable level.

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 behavioral burden and does well: it discloses the exact count (24), the family/parent/pinned-sibling structure, the terminal exception, and the selector behavior of emitted CSS. It stops short of describing return shape (strings vs. objects) or whether paths are included, which is the remaining 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 purpose is front-loaded and clear, but the bulk of the text is a 24-item name dump followed by implementation minutiae about light-dark() and :root selectors. The names are plausibly useful, yet the CSS mechanism detail reads as tangential to a discovery/list tool and inflates the description.

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 tool with no output schema, the description does the heavy lifting by explaining the theme catalog and its grouping, which is what an agent needs to call the right follow-up tool. It omits any statement of return format or whether theme file paths are exposed, leaving a small 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?

The tool takes zero parameters and the schema is empty, so there is nothing for the description to clarify; per the baseline this scores 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 opens with a specific verb+resource ('List all 24 shipped themes') and even enumerates the resource set, so the agent knows exactly what the tool returns. It does not name siblings like get_theme or search_themes to differentiate itself, but the enumerative framing makes the distinction obvious 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?

Usage is implied rather than stated: the enumeration of all themes suggests 'use this to discover what exists', and the note about data-theme sharing hints at bundle scenarios. There is no explicit 'use get_theme to fetch one' or 'use search_themes to filter', so the agent must infer the routing.

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 burden and does so well: it discloses the token population (128 required + 40 optional = 168), the full category set, which tokens were removed, and which aliases are optional. The gaps are pagination behavior and return shape, which it does not address despite limit/offset parameters.

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 with the count and categories up top. The spacing and radius notes are dense and somewhat verbose, but they supply interpretation guidance that would otherwise be unavailable given the absence of an output schema, so most 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 4-parameter tool with no annotations and no output schema, the description explains the token domain thoroughly but omits pagination semantics for limit/offset and says nothing about the response shape. It is adequate but not 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 only 25%: only 'required' is documented in the schema. The description partially compensates for 'category' by enumerating the 17 valid category values, which is real added meaning. However, limit and offset — the pagination controls — are left entirely unexplained.

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 the CSS custom-property tokens in the theme contract (scripts/theme-contract.json)', plus concrete counts and categories. An agent can distinguish it from get_token and search_tokens by the browse-all framing, though the description never names those siblings to make the contrast 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?

There is no guidance on when to choose this over search_tokens, get_token, or list_themes. The spacing/radius notes explain how to interpret tokens, not when to call this tool, so usage remains only implicitly inferable from the 'List' verb.

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?

No annotations are provided, so the description carries the full burden. 'Return' implies a safe read with no side effects, which is reasonable but unstated explicitly; there is no mention of return format (markdown), document size, auth needs, or whether content is static. For a zero-parameter static-doc reader the risk is low, but the disclosure is thin.

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. The verb and resource lead, and the clarifying parenthetical follows immediately. 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?

There is no output schema, so the description must signal the return value; 'rules, tiers, quick decisions' does sketch the content of AGENTS.md. Combined with a trivial empty schema, this is sufficient for an agent to decide whether to call it, though format and size remain unspecified.

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 nothing to disambiguate; baseline 4 applies. The schema confirms an empty object, consistent with the description's lack of parameter discussion.

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?

Specific verb ('Return') plus a named resource (AGENTS.md) with a parenthetical that describes its role as an entry point for AI coding agents. An agent can distinguish it from read_llm_txt/read_readme by content, though the description doesn't explicitly contrast with those 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?

'Entry point for AI coding agents' implies this should be read first, giving implied usage context. However, there's no explicit statement of when to use this over read_llm_txt, read_three_tiers, or read_readme, nor any exclusions or prerequisites.

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?

No annotations are provided, so the description carries the burden. It implies a safe read with no parameters and discloses the content scope. However, it doesn't state the return format (raw markdown vs structured), size, or pagination behavior, which matters for an agent consuming the result.

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 is front-loaded with the verb and resource, with the scope qualifier trailing. No 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?

For a zero-parameter read tool with no output schema and no annotations, the description tells the agent what file is returned and roughly what it contains. The main gap is the absence of any mutuality with sibling read_* tools to help routing.

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 per the rubric the baseline is 4. There is nothing further a description could add about parameters here.

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 (Return) and a specific resource (CHANGELOG.md), and adds the scope of what it contains (full release history, breaking-change notes). It is trivially distinguishable from siblings like read_versioning or read_migration which cover different documents.

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: it's a read tool for the changelog, and the mention of 'breaking-change notes' hints at a use case. But it never states when to use this versus read_versioning, read_migration, or read_readme, which are the closest alternatives in the sibling list.

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 full behavioral burden. 'Return' plus the document identity does imply a stateless, side-effect-free read and the content's nature (human-readable, not machine-parsed tokens), which is genuinely useful context. It says nothing about size, whether content is static or generated, or whether the result is truncated — minor gaps for a read-only document fetch.

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 compact sentence with the resource name front-loaded and no filler. Every word 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 zero-parameter, read-only document fetch with no output schema, the description gives the agent everything structurally necessary: the verb, the target file, and a note that the content is human-readable rather than machine-parseable. Only the absence of any output-shape hint keeps it below a 5.

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 declares zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description correctly implies a parameterless call.

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 ('Return') and a named resource ('CONTRACT.md — human-readable token contract'), so the agent knows exactly what the tool fetches. It does not, however, distinguish itself from the many sibling read_* document tools (read_llm_txt, read_readme, read_theming), which share the same shape and would be equally plausible from the name 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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative among the read_* siblings. Usage is only implied by the filename, which for a document-fetch tool is reasonably self-evident but leaves the agent to infer when the token contract is the right document to consult.

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?

No annotations are provided, so the description must carry the behavioral load. 'Return' correctly implies a read-only, side-effect-free operation, and 'single-fetch' hints that one call yields the whole payload, but it says nothing about response size, format, or caching behavior. Adequate but thin for a no-annotation 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?

A single front-loaded sentence with no filler; the resource and its purpose are stated immediately with nothing 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 zero-parameter, zero-annotation tool with no output schema, the description is serviceable but not complete: an agent cannot tell what sections llm.txt actually contains or how it relates to the sibling read_* documents. Given the tool's simplicity the gap is modest, but it leaves routing decisions to inference.

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 the baseline is 4; the schema trivially covers 100% of the (empty) parameter set and there is nothing for the description to compensate for. No parameter ambiguity exists.

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 (Return) plus a specific resource (llm.txt) and characterizes its role as the 'canonical single-fetch summary for AI agents', which differentiates it from the many sibling read_* tools that fetch individual docs. An agent can tell what this returns without opening anything else.

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 'single-fetch summary for AI agents' implies this is the consolidated entry point, so the usage is inferable, but the description never says when to prefer this over read_readme, read_agents, or the other read_* siblings. No explicit when/when-not guidance is given.

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 bears full disclosure burden; it does communicate that this is a static document fetch of a named file with a defined version scope, which is the key behavioral fact. It omits whether the content is read-only, paginated, or returns raw markdown, but for a zero-parameter fixed-file read these gaps are minor.

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 naming the file and its payload; every clause earns its place with no filler or redundancy.

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 exists, so the description must signal the return content, and it does by listing the categories of information in the guide. Nothing an agent needs in order to call a parameterless document reader is missing, though the relationship to overlapping sibling docs remains unstated.

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 declares zero parameters, so there is nothing to disambiguate and the baseline is 4. The description's version range (v0.7 → v0.8) usefully clarifies that no version argument is needed, since the file is fixed.

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 a specific resource (MIGRATION.md) and enumerates its contents (renames, removed features, breaking changes) plus the exact version range v0.7 → v0.8, so an agent knows what it gets. It does not explicitly differentiate itself from nearby siblings like read_changelog or read_versioning, which also cover version history.

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 version span 'v0.7 → v0.8' implies the usage condition (consult when migrating between those versions), but the description never states when to prefer this over read_changelog, read_versioning, or read_readme, nor any exclusions. Usage 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?

No annotations are provided, so the description carries the full disclosure burden. It does tell the agent this is a plain content read of a named file, which is inherently safe and side-effect free, but it says nothing about format, truncation, or whether the file might be absent.

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 fragment with no wasted words; the file identity and content scope are front-loaded. It is slightly clipped in phrasing but efficient and appropriately sized.

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 document fetch with no output schema, the description covers what an agent needs: which file and what it contains. Only minor gaps remain, such as the return format or behavior when the file 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 zero parameters, so there is nothing for the description to explain beyond what the empty schema already conveys. Baseline of 4 applies for a parameterless 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?

Names a specific resource (README.md) and a specific verb (Return), plus the content scope ('top-level install + usage'). This implicitly distinguishes it from the many read_* siblings (read_changelog, read_theming, read_agents) that each target a different document, but it never explicitly contrasts itself with those 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?

Saying the file covers 'top-level install + usage' implies when an agent would want it (initial orientation), but there is no explicit when-to-use guidance and no routing between this and alternatives such as read_llm_txt or read_agents. Usage is inferable, 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?

No annotations provided, so description carries the burden. It reveals the operation is a read-only lookup of a named document, which is informative, but doesn't state whether content is static, cached, or its size/scope limits. Minimal but accurate disclosure.

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?

Single short sentence, front-loaded with the target document and scoped to its content. No waste.

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 no-param document reader with no output schema, the description sufficiently states what is returned. It could route better among the ~30 sibling tools, but the tool itself is fully described.

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?

Zero parameters, so baseline is 4. Nothing to explain and no schema gap to compensate for.

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 (Return) and resource (THEMING.md) and describes its content scope (theme authoring + override patterns). It's clear what it does, though it doesn't explicitly differentiate from sibling read_* tools like read_readme beyond the filename 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?

Implied usage: fetch this doc when you need theme authoring/override info. No explicit when-to-use vs alternatives (e.g., get_theme or list_themes). Adequate but thin given the many 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?

No annotations are provided, so the description carries the burden. It implies a read-only static doc fetch, but says nothing about return format, length, or whether the file always exists. For a zero-parameter documentation read the risk is low, so this is an acceptable but not rich disclosure.

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 naming the file and immediately summarizing its contents. No 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?

For a trivial static-document read with no parameters, no annotations, and no output schema, the description gives enough to know what comes back (the three authoring tiers). Only minor gaps, such as the file's scope or format, are left open.

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 has zero parameters, which is the documented baseline for a 4. The description correctly implies no arguments are needed to fetch the file.

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 (Return) and resource (THREE-TIERS.md), then clarifies the content: the three authoring tiers (mixin / utility class / bare tag). This distinguishes it from sibling doc readers like read_theming or read_llm_txt, though it doesn't explicitly contrast them.

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: an agent should call it when it needs to understand the mixin/utility-class/bare-tag tier model. There is no explicit when-to-use, when-not-to-use, or named alternative among the many read_* siblings.

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 provided, the description carries the full behavioral burden. It does disclose the payload (which sections of VERSIONING.md are returned), which is genuinely useful, but says nothing about whether the content is live or a static snapshot, its size, or whether it is mutable or cacheable. Adequate but incomplete for a zero-annotation 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?

A single front-loaded sentence with no filler: resource first, then the three content areas. Every clause earns its place and nothing is repeated.

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 zero-parameter document retrieval with no output schema, the description does the essential work by enumerating the returned content so the agent knows what to expect. No output schema exists, yet the description substitutes for it reasonably well; only the lack of any sibling routing guidance keeps it from a 5.

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 the schema contributes nothing to explain. The baseline for a no-parameter tool is 4, and there are no parameters whose meaning the description would need to disambiguate.

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 ('Return') and an exact resource ('VERSIONING.md'), then enumerates the three content areas the file covers (semver policy, deprecation lifecycle, Conventional Commits→changelog mapping). This is well beyond a tautology, but it never distinguishes itself from the closely related sibling read_changelog, which an agent could easily confuse given the 'changelog mapping' phrase.

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 content enumeration lets an agent infer that this is the right tool when it needs versioning/deprecation policy, but there is no explicit when-to-use statement and no routing guidance versus read_changelog or read_migration. 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?

With no annotations, the description carries the burden and does so well: it discloses the branching behavior (cia.grid(n) when exactly on grid, cia.px(value) when off-grid) and the shape of the response. It stops short of noting any failure modes or whether px must be positive, but for a pure computation tool this is nearly complete.

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 purpose, then return values, then agent-specific instructions — every sentence earns its place and the agent directive is valuable routing. It is slightly long for a two-parameter tool, but nothing is 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?

There is no output schema, so the description must explain the return payload, and it does so fully (step number, SCSS call, rem, note). Combined with usage guidance and the docs pointer, an agent has everything needed to call and interpret 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 coverage is 100% and both parameters are already documented in the schema, including the 'default 4' for base. The description reinforces the 4px grid context but adds no new syntax or format detail beyond what the schema states, 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 opens with a specific verb+resource ('Snap a design px value to cia's 4px geometric grid') and then enumerates exactly what is returned (step number, SCSS call, rem, note). This is plainly distinguishable from the read/search siblings, none of which perform grid snapping.

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 trigger ('call this whenever you get a px value from a design tool (Figma, mockup, screenshot)') plus a hard exclusion ('NEVER write raw rem/px literals when a cia function applies') and points to the decision tree at /docs/composition. No inference is required.

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?

No annotations are provided, so the description carries the full behavioral burden. It reveals the search scope, but says nothing about case sensitivity, match ordering/relevance, pagination beyond the limit cap, or whether results are truncated. For a search tool with zero annotation coverage this is a real 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?

A single front-loaded sentence with no filler or restatement of the tool name. Every clause earns its place by specifying search scope.

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 annotations, no output schema, and 0% schema description coverage, the description should carry more: return shape, ordering, and the limit default are all unaddressed. It is adequate on scope alone but incomplete 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 0%, so the description must compensate. It does clarify what 'query' matches against (names, descriptions, and mixin sub-fields), which is genuine added value; however, it says nothing about 'limit' beyond the schema's min/max constraint, and no default or result-cap behavior is described.

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 a specific verb (substring search) and resource (components), and enumerates the searchable fields: names, descriptions, and mixin names/signatures/docs/bodies. That distinguishes it from list_components/get_component and from search_functions/search_mixins, though the differentiation is implicit via the resource 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?

No guidance on when to prefer this over list_components, get_component, or search_mixins. The only hint is the word 'substring search', which implies discovery-by-text, but no conditions, prerequisites, or exclusions are given.

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 behavioral burden. It does disclose the searchable scope (names, signatures, docs, and bodies), which is genuinely useful, but says nothing about case sensitivity, ranking/relevance ordering, pagination, or whether results are truncated.

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 the search scope front-loaded and no filler. Its only weakness is that this brevity is partly achieved by omitting information an agent needs, but as pure structure it is efficient.

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 search tool this covers the core operation, but with no output schema the description should ideally state result shape and how limit truncates, and with no annotations it should note the read-only nature. Adequate but with visible 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?

Schema description coverage is 0%, so the description must compensate and it does not: neither 'query' nor 'limit' is mentioned. The meaning of limit (1-200 cap on results) and whether query supports syntax beyond plain substrings are left entirely undocumented.

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 specific verb and resource (substring search over functions) and even enumerates the searched fields (names, signatures, docs, bodies), which is more than a tautology. It does not, however, explicitly distinguish itself from the sibling list_functions or get_function, so the agent must infer the search-vs-list-vs-fetch distinction.

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 byte-level matching semantics ('substring search') implicitly tell the agent this is the lookup tool for partial/unfamiliar names, as opposed to list_functions (enumerate) or get_function (fetch one). But no alternative is named and no when-not condition is given, so the routing 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?

No annotations, so the description carries the full burden. It doesn't state whether search is case-sensitive, whether results are ranked or paginated, or how substring matching behaves. Only the target fields 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?

A single efficient sentence with zero waste, front-loading the verb and target fields.

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 annotations, no output schema, and 0% parameter coverage, the definition is too thin for a 3-parameter search tool. It should explain matching behavior, category filtering, and limit semantics.

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 schema documents nothing about query, limit, or category semantics. The description names the searched fields but provides no parameter guidance, leaving all three parameters undocumented.

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 (substring search) and the resource fields searched (names, signatures, docs, bodies). It distinguishes itself from list_mixins and get_mixin, though it doesn't explicitly contrast with the closely related search_functions sibling.

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 word 'search' implies usage over list_mixins/get_mixin, but no explicit when-to-use guidance or alternatives are stated. An agent must infer the search-vs-enumerate distinction.

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?

No annotations are provided, so the description bears full behavioral burden. It discloses the match type (substring) and the searched fields, which is useful, but says nothing about case sensitivity, result ordering, pagination/default limit behavior, or the return shape.

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 efficient sentence with the search scope front-loaded and zero filler. Arguably too terse for a tool with 0% schema coverage, but structurally sound.

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 read-only search tool with no annotations and no output schema, the description covers the core search semantics. It is still missing limit/pagination behavior and return-format hints, leaving a modest gap 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?

With 0% schema description coverage, the description must compensate. It clarifies what the required 'query' matches against (theme names, descriptions, token values), which is genuinely useful. However, the 'limit' parameter (1-50, default unknown) is entirely unexplained in both schema and 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?

States a specific verb ('Substring search') and specifies the searchable fields (theme names, descriptions, token values). Clear on what it does, but does not differentiate itself from the sibling list_themes or get_theme, leaving the agent to infer the distinction.

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?

Provides no when-to-use guidance, no prerequisites, and does not mention alternatives such as list_themes or get_theme. The agent must guess whether to search or enumerate.

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?

No annotations are provided, so the description carries the full behavioral burden. It does not disclose case sensitivity, match semantics (prefix vs anywhere in the string), paging behavior, or the default/effective value of limit, leaving the agent to guess at runtime 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?

A single front-loaded sentence with no filler, which is well sized for the tool. It is efficient, though the brevity contributes to the under-specification scored elsewhere.

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 annotations, no output schema, and three undocumented parameters, the description does too little. It omits the return shape, result ordering, limit default, and matching behavior an agent needs to call it 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 description coverage is 0% across three parameters. The phrase 'token names and categories' loosely maps to query and category, but the limit parameter (1-500) is entirely unexplained and no format or matching rules are given for query.

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 (substring search) and resource (token names and categories), which is meaningfully distinct from the sibling list_tokens (enumeration) and get_token (single fetch). It stops short of explicitly naming those siblings as alternatives, so it is clear but not fully disambiguating.

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 word 'search' implies a lookup use case, but the description never states when to use this instead of list_tokens, get_token, or search_functions. No prerequisites, exclusions, or routing guidance are given for 30 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?

No annotations, so the description carries the full burden and mostly succeeds: it discloses that it does not compile Sass, what it checks (required tokens + contrast pairs), and what it returns (missing tokens with mode 'per-file' vs 'consolidated', a11y warnings per pair). It does not state whether validation is read-only/pure or whether errors throw vs return, but the return-shape detail is unusually rich for an unannotated validator.

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 the core verb+scope, then the custom-theme applicability, then input format and return shape. Efficient, though the parenthetical about mode shapes is slightly heavy for a description.

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 2-param validator with no output schema and no annotations, the description covers scope, non-applicability (Sass), expected input shape, and return content. It is complete enough to call correctly; only the error/throw behavior is unspecified.

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 both parameters are already documented in the schema (including the 'not .scss source' hint on css and the cosmetic nature of label). The description reinforces the CSS-format constraint but adds no syntax or format detail beyond the schema, so 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 (validate), specific resources (theme CSS against a token contract and WCAG contrast audit), and distinguishes scope explicitly ('Not scoped to cia's own themes'). An agent can tell it apart from all sibling list_/get_/search_/read_ tools without opening the 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?

Provides explicit when-to-use ('works on a fully custom theme you just built, e.g. via derive-theme assemble_prompt'), a crucial when-not-to-use exclusion ('does not compile Sass, give it the output, not .scss source'), and names the equivalent npm check as ground truth. Nothing 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.