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

The description discloses a specific failure mode ('Fails with DUPLICATE_ID if the id already exists') and implies a persistent write operation. However, with no annotations provided, it does not disclose side effects, permissions, reversibility, or response behavior, leaving a meaningful transparency gap for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. Critical information is front-loaded: the action, the duplicate-failure condition, the alternative tool, and the required pre-check. Every sentence 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?

Despite the tool's 13 parameters, heavy nesting, and no output schema, the description only covers duplicate handling and pre-checks. It omits basic guidance on required fields beyond id/name, the meaning of nested structures, and what a successful or failed response contains. For a tool this complex, the description is not complete enough.

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%, and the description does not compensate for the 13 parameters. It only implicitly clarifies that 'id' must be unique and new; it provides no guidance on name, tags, rules, design, implementations, or other complex nested fields. The schema provides names and types, but the description adds almost no semantic value for the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Register a brand-new design component.' It clearly distinguishes itself from registry_update_component by stating the id-exists condition and naming the alternative tool, so an agent can select correctly without inspecting all 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 description gives explicit usage guidance: use registry_update_component when the id already exists, and only create when registry_find_component and registry_find_by_design_reference confirm no equivalent component exists. This is strong when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does not mention what happens on duplicate ids, whether components must already exist, whether the operation is idempotent, or what validation is performed. For a write operation, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler or repeated schema details. It is concise, though its brevity contributes to the lack of behavioral and parameter context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A 12-parameter mutation tool with no annotations and no output schema needs substantially more context. The description omits return behavior, required fields, validation, uniqueness semantics, and relationships between parameters, leaving the agent under-equipped to invoke 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%, and the description only vaguely maps to the 'components' field by saying patterns are composed of components. It gives no guidance on required id/name constraints, status enum values, design structure, or the meaning of fields like layoutRules and compositionRules.

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, 'Register', and a clear resource, 'brand-new higher-level UI pattern composed of one or more components.' This distinguishes it from sibling create tools for components and tokens by emphasizing the pattern-level scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance about when to use this tool versus alternatives like registry_update_pattern or registry_create_component. It explains what the tool does but not the conditions or exclusions that should drive selection.

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 must carry behavioral transparency. It discloses that the tool fails with DUPLICATE_ID on conflicts and implies a persistent write operation. However, it does not mention auth requirements, response behavior, or any other side effects beyond the duplicate 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 dense sentence that front-loads the core action, then states the failure mode and the alternate tool. Every word contributes meaningful routing or behavioral information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations, no output schema, and zero schema descriptions, the definition leaves important gaps. It covers the create-vs-update decision and the duplicate behavior, but it does not explain required parameter semantics or what happens on success, making it incomplete for an agent constructing a valid call.

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% and the description adds no parameter-level meaning. It only indirectly references id uniqueness. For 9 parameters including ambiguous ones like type, usage, source, and aliases, the description fails to compensate for the missing schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a create action on a specific resource: 'Register a brand-new design token.' It also distinguishes itself from the sibling registry_update_token by explicitly framing the duplicate-id case, so an agent can tell them apart without inspecting schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool: for a brand-new token. It also names the alternative for existing ids: 'use registry_update_token instead.' This is clear routing guidance with no inference 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that deprecation is non-destructive, history remains in git, and agents can still see past component mappings. This is meaningful behavioral context beyond the tool name. It does not mention whether deprecated components are hidden from default listing or whether the operation is reversible via update, but the core behavior is well covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler. The key action is stated first, and the second sentence adds important design context about why there is no delete. Every sentence 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 simple tool with three parameters and no output schema, the description plus schema is mostly adequate. It explains the operation's purpose and its non-destructive nature. The main gap is the lack of parameter semantics for 'reason', and there is no mention of what the response contains, but for a non-destructive marking operation this is a minor omission.

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 33%, and the description adds no parameter-level meaning. The 'id', 'reason', and 'replacedBy' parameters are left mostly to inference; only 'replacedBy' has an inline schema description. The description does not compensate for the low schema coverage, so an agent may not know the purpose of 'reason' or how 'replacedBy' relates to deprecation.

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 ('Mark') and resource ('a component'), and clearly distinguishes this operation from deletion: 'There is no destructive delete operation for components by design.' It is immediately obvious what the tool does and how it differs from sibling tools like registry_update_component or registry_create_component.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent when to use this tool: when the intent is to deprecate rather than delete, and it notes that deletion is not available at all. It does not explicitly list alternative tools for other operations, but the 'instead of deleting it' framing gives clear contextual guidance for the primary decision.

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 responsibility, and it delivers: it discloses determinism, the three possible return statuses, what each status contains, and the critical 'never guesses' rule. This adds real behavioral context beyond the tool name and schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with distinct jobs: scoping the operation, specifying return outcomes, and adding a behavioral caveat. No filler, no repetition of schema details, and the most important distinguishing facts are front-loaded.

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 explains return statuses well despite the lack of an output schema, but it leaves input-contract gaps: with five optional-looking params and no annotation, an agent isn't told which combinations are valid or what error behavior looks like. Strong on outcomes, weaker on operational prerequisites.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description only adds the fileKey/nodeId pair example and does not clarify valid parameter combinations or precedence among url, fileId/nodeId, and name, but the schema already documents each parameter individually.

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 precise verb ('resolve') and resource ('design-tool reference to a registered component'), with concrete examples like Figma fileKey/nodeId. The determinism and status vocabulary further distinguish it from generic sibling search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies the right context: use when you have a design-tool reference and need the matching registered component. However, it never contrasts with siblings like registry_find_component or registry_get_component, so the agent gets no explicit when-not-to-use or alternative-selection guidance.

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

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

With no annotations provided, the description carries the behavioral burden, and it does well by disclosing that the search is deterministic and non-semantic, which prevents misuse. It also clarifies the search scope across multiple fields, though it could mention that it returns multiple matches or how results are ordered, a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero waste: the first defines scope and behavior, the second immediately routes to alternatives. Critically, the negative constraint ('NOT semantic/AI search') is front-loaded, which is exactly what an agent needs to see first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no output schema, the description is complete for invocation and selection purposes. It covers scope, behavior, limitations, and alternatives, leaving no obvious gap that would cause mis-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?

The schema covers the single parameter fully (free-text, case-insensitive substring), and the description reinforces that the query is a plain substring match, not AI-based. This adds meaningful context beyond the schema, especially the negation of semantic behavior.

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 ('Deterministic substring search') and a clear resource ('component id, name, aliases, tags, and description'), immediately distinguishing it from semantic search. It explicitly names the siblings it is not, which clarifies its unique role in the registry toolset.

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 explicitly says when to use this tool (when you have a partial query) and when not to use it (when you already know an exact identifier), and names the two alternatives: registry_get_component and registry_find_by_design_reference. This leaves no ambiguity about tool selection.

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 present, so the description carries the burden of behavioral disclosure. It transparently states that missing IDs produce an error and that matching is exact, which is useful and sufficient for a simple read operation.

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 conveys the core action, the identifying key, and the failure behavior with no wasted words. Every clause adds meaning.

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 read operation with no output schema, the description covers the essential behavior: what it fetches, how to identify the item, and what happens when it is absent. It stops short of describing the returned component shape, but that is acceptable given the simple, single-entity scope.

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 already documents the id parameter thoroughly, including its pattern and 'stable registry id' meaning. The description adds only the 'exact' qualifier and error behavior, which is marginal value beyond the schema, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('fetch'), a specific resource ('a single component'), and the lookup key ('its exact stable registry id'). It differentiates itself from sibling tools like registry_list_components and registry_find_component by emphasizing exact-id retrieval of one component.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the usage context clear: use this when you have the exact stable registry id for one component. It implies that fuzzy or partial lookup belongs elsewhere (e.g., registry_find_component), but it does not explicitly name alternatives or state when not to use it.

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 states the tool returns a manifest and lists its contents, which suggests a read-only operation, but it does not disclose behavior when the registry does not exist or whether any side effects occur. This is acceptable but not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences provide the resource, the returned fields, and the intended usage without wasted words. The key purpose is front-loaded.

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 metadata retrieval tool, the description covers what it returns and how it should be used. No output schema exists, but the listed manifest fields give sufficient expectation of the result.

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?

There are zero parameters, so schema coverage is trivially complete. The description adds contextual meaning by explaining what the manifest contains, but parameter-specific semantics are not needed 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?

The description clearly states a specific action ('Return') and a specific resource ('the registry's manifest'), and enumerates its contents: schema version, registry version, project info, and configured design tool(s). This distinguishes it from sibling tools like registry_get_component or registry_validate.

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 explicitly says 'Use this first to confirm a registry exists and understand what project it describes,' giving clear contextual when-to-use guidance. It does not mention alternatives or exclusions, so it stops short of a perfect score.

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 behavioral burden. 'Fetch' implies a read operation and the description states what is included in the result. However, it does not disclose error behavior for missing ids, return shape structure, or whether composed components are full objects or references. The description adds some context but not comprehensive detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single focused sentence that front-loads the verb and resource, states the key constraint, and notes what is included in the result. There is no wasted wording or redundant repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter getter with no output schema, the description covers the essential facts: what to fetch, by what id, and what the result includes. It is complete enough for an agent to invoke the tool correctly, though a note on not-found behavior would make it fully robust.

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 provides no description for the 'id' parameter (0% coverage), so the description must compensate. The phrase 'exact stable registry id' adds semantic meaning beyond the raw schema, indicating the id must be an exact, stable identifier rather than a search term. Still, it does not explain id formatting, examples, or how the id relates to pattern versions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Fetch'), the resource ('a single UI pattern'), and the lookup mechanism ('exact stable registry id'). It also adds a meaningful detail about the response ('including the components it composes'). It does not explicitly distinguish itself from sibling tools like registry_get_component or registry_get_token, but the resource type makes the distinction reasonably clear.

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 'by its exact stable registry id' provides clear context: use this tool when you already have the precise, stable id of a pattern. It does not mention alternatives or exclusions, but for a simple get-by-id operation the usage context is adequately implied.

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

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

With no annotations, the description carries the behavioral burden and conveys that this is a read-only retrieval by using 'Return' and by framing it as a preliminary read. It also adds detail about 'full set' and gives illustrative rule examples, but it stops short of describing output format or failure modes, which are minor for a parameterless getter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff, with the core behavior first and the usage context second. The examples earn their place by making the rule type concrete, and every clause adds value.

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, no-output-schema read tool, the description adequately covers what it returns and when to call it. It could be more explicit about the returned data shape or how to handle an uninitialized registry, but the current guidance is sufficient for correct invocation in the stated workflow.

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?

There are zero parameters, so there is no param semantics for the description to add. The description usefully explains what the returned rules will contain, which is the relevant information an agent needs for this no-input tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Return') and resource ('full set of structured design/engineering rules') with concrete examples, which clearly differentiates it from sibling tools like registry_update_rules or registry_get_manifest. The title 'Get project rules' is also reinforced by a substantive description rather than repeated.

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 explicitly says to read this before generating UI code, giving clear situational guidance. It does not name sibling tools or state when not to use it, but the intended context is clear enough for a getter.

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 burden, and it does well by indicating a read-only fetch operation and exact-match behavior. It doesn't disclose edge-case behavior like not-found handling or return format, but for a straightforward single-item getter this is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one tightly packed sentence with no filler. The core action and object are front-loaded, and every word adds clarity.

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 single-parameter getter, the description is sufficient to invoke the tool: the agent knows what to pass and what kind of result to expect. It omits return details and error behavior, but there is no output schema and the tool's simplicity lowers the burden.

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%, but the description adds meaningful semantics to the sole 'id' parameter by labeling it a 'stable registry id' that must match exactly. This helps the agent understand the id's role beyond the raw schema pattern, though it doesn't elaborate on the allowed format beyond what the schema already provides.

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 ('Fetch') and a specific resource ('a single design token'), and clarifies the lookup mode ('by its exact stable registry id'). This distinguishes it from sibling tools like registry_list_tokens or registry_find_component without needing to inspect their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies the tool is for direct retrieval when the caller already knows the exact stable registry id, not for searching or listing. It doesn't explicitly name alternatives, but the 'exact stable registry id' precondition gives clear context for when to choose this tool.

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 behavioral disclosure itself. It discloses that the tool creates files, that it fails on an existing registry, and that force=true is the escape hatch; combined with the force parameter description ('Overwrite an existing registry'), an agent understands the destructive potential.

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 conveys action, artifact layout, and failure/force behavior with zero filler. Every clause adds decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an initialization tool, it covers the main deliverables and the key failure mode, and the sibling list shows this is the creation entry point. It is missing how 'resolved registry path' is derived and what a successful response looks like, but those are secondary to safe usage.

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 description does not explain any parameter semantics; only force and designTool have schema descriptions. The required projectName and the projectDescription param are left undocumented in both the schema and description, weakening the agent's ability to fill them correctly.

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 action ('Create a complete starter registry') with a precise resource path and file list (.design/registry/{manifest,components,tokens,patterns,rules}.json + README). The failure condition also separates it from sibling tools that read or modify an existing registry.

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?

Clearly implies the intended context: call when a new registry needs to be initialized at the resolved path. It also gives a key usage condition ('Fails if a registry already exists there unless force=true') that tells an agent when a parameter is needed, though it does not explicitly name 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 provided, the description carries the burden of behavioral disclosure. It conveys a read-only browsing purpose through words like 'List' and 'browse', but does not mention result format, pagination, default status behavior, or whether filters can be combined. This is acceptable for a simple list tool but leaves some behavior unspecified.

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 concise sentences: the first states action and filters, the second provides the practical use case. No wasted words, and the most important information is front-loaded.

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 tool is simple—two optional parameters, full schema coverage, no nested objects. The description covers what is listed, the filters, and the intended workflow. Minor omissions like output shape or ordering do not significantly hinder use, but the lack of annotation support means a small gap remains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters fully. The description only restates that filtering by lifecycle status or tag is possible, adding no deeper semantic meaning such as matching rules or filter combination behavior.

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 action ('List all design components in the registry') and clearly identifies the resource and available filters. It distinguishes itself from sibling get/find tools by emphasizing the broad, all-items browsing behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit practical guidance: 'Use this to browse what already exists before proposing a new component.' It does not explicitly name alternatives or exclusion cases, but the intended context is clear enough for an agent to select it appropriately.

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 communicates a read-only enumeration ('List all') and the project scope, but it does not disclose ordering, pagination, or output 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?

One sentence, front-loaded with the core action and resource, with examples that add clarity without unnecessary length.

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 listing tool, the description is mostly complete: it states the action, resource, and scope. It does not specify the return format, which is a minor gap given the low complexity and absence of an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero properties, so there are no parameters requiring explanation. The baseline for a zero-parameter tool is 4, and the description does not need to add parameter detail.

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 action ('List') and a concrete resource ('higher-level UI patterns'), with examples such as empty state and search toolbar that distinguish patterns from components or tokens. The 'registered in the project' scope further clarifies what is being listed.

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 use this tool versus alternatives. It does not mention that registry_get_pattern should be used for a single pattern, or that registry_list_components is for component-level listings.

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 must carry the behavioral burden; it clearly identifies the operation as non-mutating ('List'), but it does not mention pagination, response size, or return shape. This is acceptable for a simple read-only listing tool, though it adds minimal beyond the core action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence and 13 words; the action and optional filter are front-loaded. There is no filler or repetition.

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 tool with one optional parameter and no output schema, the description plus the enum schema is sufficient for an agent to invoke it correctly. It lacks only nonessential details such as response format and relationship to registry_get_token.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description partly compensates by stating the category filter is optional and giving examples. However the examples duplicate the enum values, and the description does not explain how filtering behaves beyond the parameter name.

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 ('List') and resource ('design tokens'), and clarifies it returns the full collection ('all') with an optional category filter. It is distinguishable from siblings like registry_get_token and registry_create_token, though it does not explicitly call out any alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied by the list semantics and the optional category filter, but there is no explicit guidance on when to use this tool instead of registry_get_token or when a create/update operation would be appropriate. No exclusions or alternative routing are 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 provided, the description carries the full behavioral disclosure burden. It clearly states partial-update semantics, so an agent knows omitted fields are preserved, and it exposes the NOT_FOUND failure mode for missing ids. It does not describe return values, auth, or validation effects, but the core PATCH contract is sufficiently transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The operation and target are front-loaded, the patch semantics follow immediately, and the error behavior plus alternative tool are condensed into the final clause. Every sentence 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 mutating tool with no annotations, no output schema, and a large nested input schema, the description supplies the key facts needed for selection and invocation: it is a partial update, id is required, and missing ids are an error with a known alternative. It could be more complete by mentioning relationships to registry_update_rules or registry_deprecate_component, but the current description plus rich schema is enough for an agent to call it correctly in the common case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero description coverage and 13 parameters, so the description must compensate. It adds the most important parameter-level semantic: only provided fields are changed, and omitted fields are left untouched. This generalizes across all 12 optional parameters. It does not explain nested partial-object behavior, such as partially specifying the rules object, but the schema still provides types, required fields, and defaults.

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 opening sentence, 'Patch an existing component by id', gives a specific verb, resource, and selection mechanism in one line. The closing clause explicitly distinguishes it from registry_create_component, so an agent can immediately separate update from create without deeper inference.

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 provides a concrete routing rule: if the id does not exist, the call will fail with NOT_FOUND and the agent should use registry_create_component instead. It does not address every sibling overlap, such as when to use registry_update_rules or registry_deprecate_component for component subfields, but the main create-vs-update decision is clearly 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 present, so the description itself must disclose behavior; it does add the specific NOT_FOUND error condition, which is useful and non-obvious. It does not disclose whether PATCH means merge or replace, what happens to omitted optional fields, or what is returned, leaving significant behavioral ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two terse sentences with no filler; the primary action and resource are front-loaded, and the error behavior is placed second. Each word earns its place, making it highly scannable.

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 12-parameter update tool with no annotations and no output schema, the description leaves out critical context such as partial update semantics, response content, and the meaning of the many optional fields. The single NOT_FOUND detail is helpful but far from sufficient for safe invocation without other sources.

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%, and the description only clarifies the role of the required 'id' parameter. The other 11 parameters (design, layoutRules, usageConstraints, etc.) receive no explanation beyond their names in the schema, so the description fails to compensate for the low coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the operation as 'Patch an existing pattern by id,' with a specific verb and target resource, and implicitly distinguishes itself from siblings like registry_create_pattern (which creates) and registry_get_pattern (which reads). It is unambiguous and immediately scopes the tool.

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 'existing pattern' and the NOT_FOUND failure mode tell an agent this tool should only be applied to already-created ids, but no explicit alternative is named. The description does not say 'use create_pattern for new ids' or otherwise state exclusions, so guidance relies on inference from the word 'existing.'

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 behavioral disclosure burden. It clearly states the destructive, whole-document nature of the operation and the rationale ('deterministic and diff-friendly'), which is valuable behavioral context beyond the schema. It does not disclose validation behavior or side effects on dependent entities, but the core overwrite semantics are well covered.

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 concise sentences, each earning its place. The first states the operation, the second explains the required payload semantics and the reason behind the design. It is front-loaded and contains no filler or repetition.

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 tool with a single parameter and a detailed input schema, the description is largely complete: an agent knows what action is performed and exactly how the rules list should be supplied. The absence of an output schema means the agent does not know the result format, but that is not essential for correctly invoking the operation. Minor gaps include error/validation behavior and how to retrieve current rules first, but these do not block correct use.

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 provides structure for the single 'rules' parameter but no prose descriptions (0% coverage). The description compensates by explaining the critical semantic: the array must contain the complete desired rule set, not a partial update. This is essential meaning beyond the schema, though it leaves the subfields of individual rules to the schema, which already defines them reasonably well.

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 and resource: 'Replace the full set of structured design/engineering rules.' It also makes the key distinguishing property explicit — this is a full-document replace, not a delta — which separates it from read-only getter tools and from component/token/pattern updaters in the sibling list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear, actionable usage guidance: when replacing the rules, send the complete desired rule list, not a delta. This makes the invocation pattern obvious and excludes incremental updates. It does not explicitly name alternatives, but the full-document replace instruction effectively prevents an agent from treating this as a merge operation.

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

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

The description discloses one useful failure behavior: it fails with NOT_FOUND if the id does not exist. However, there are no annotations, so the description carries the full burden; it does not mention side effects, partial vs. full update semantics, immutability of fields, permissions, or return value behavior. This is minimal coverage for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tight and front-loaded: two sentences, no filler. The core requirement and a key failure mode are stated efficiently. It is concise, though it sacrifices substantive guidance that would be more valuable than additional prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (11 parameters, nested objects, no annotations, no output schema), this description is incomplete. An agent has no way to understand how to populate most fields, what the update response looks like, or what constraints apply beyond the id. It covers only the most basic invocation scenario.

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%, and the tool has 11 parameters, yet the description only references the id parameter. None of the other fields (name, type, usage, value, aliases, category, deprecated, deprecation, description) are explained, and the nested deprecation object and heterogeneous value type remain entirely undocumented in both the 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?

The description clearly states the operation: 'Patch an existing token by id.' This identifies the verb, resource, and scope, and distinguishes it from create/get operations by the word 'existing.' It does not explicitly name sibling alternatives, but the meaning is 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: use this tool to modify an existing token by id, rather than to create or read a token. However, there is no explicit guidance about when to choose this over registry_create_token or registry_get_token, and no mention of whether this is the only way to update token metadata.

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 behavioral disclosure burden. It states that if anything is wrong, it returns valid=false with a list of issues, which is useful and specific. It does not explicitly state that the operation makes no changes to the registry, but 'validate' strongly implies a read-only check, and the failure-output behavior is well 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?

The description is concise and front-loaded: it states the main action and scope first, then enumerates validation categories, then gives the return behavior. Every sentence earns its place without unnecessary 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 tool with no output schema, the description provides enough context to call it correctly and interpret a failure result. It does not describe the exact structure of the issue list or explicitly state the success return shape (valid=true), but these are minor gaps given the simplicity and purpose of the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there are no parameter semantics to document. The baseline of 4 applies because the description still clarifies that validation covers the whole registry, eliminating any ambiguity about scope even though the input schema is empty.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as a comprehensive validation operation over the entire registry, listing specific validation checks like duplicate ids, broken cross-references, and circular references. This is distinct from the sibling CRUD and retrieval tools, so an agent can immediately understand what the tool is for.

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 makes the use case clear: run validation across the whole registry when integrity issues need to be checked. It does not explicitly mention when not to use it or point to alternatives, but the sibling tools are all get/list/create/update operations, so the contrast is obvious. A brief note about running after mutations would be a minor improvement.

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