Marmo UI MCP

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does mention the Marmo overlay feature for inline comments, but it does not disclose side effects (e.g., what 'register' does, whether it creates a persistent record), permissions, or prerequisites. This is a significant gap for a mutation-like 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 concise, front-loaded sentences with no redundant or low-value information. It efficiently conveys the core purpose and a key feature.

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 simple schema (3 params, 1 required) and full schema coverage, the description adequately covers the basic intent. However, it lacks usage context (when to use vs. alternatives) and behavioral details (side effects, permissions), making it only partially complete for an agent making a decision.

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%, with all three parameters having descriptions in the schema. The description itself adds no param-specific detail (e.g., that prototypeId is a slug or that deployUrl is optional), so it does not go beyond the schema.

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

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

The description clearly states the verb 'register' and the resource 'prototype', and mentions the share URL outcome. It distinguishes itself from sibling tools like get_prototype_feedback by focusing on registration and sharing, though it could more explicitly name the alternative for feedback.

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

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

The description implies the tool should be used when you want to register a prototype for sharing, but it does not explicitly state when not to use it or provide alternatives. There is no exclusionary guidance, but the intent is reasonably clear.

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 transparency burden. It discloses the validation step and optional saving, but it does not state what happens on validation failure, the return format, or any permission requirements. This is a partial 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?

Two sentences, front-loaded with verb and resource, no redundant wording. Every sentence earns its place: one for purpose, one for workflow and use case.

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 absence of an output schema and annotations, the description covers the core purpose, workflow, and use case well. It could mention return values or failure behavior, but the essential context is present.

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 does not add any parameter-specific meaning beyond what the schema already provides; it focuses on the workflow rather than parameter details.

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

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

The description clearly states the tool validates and optionally saves a custom component for the authenticated tenant. It specifically mentions running review_generated_code validation before persisting, which distinguishes it from sibling tools like review_generated_code that only 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?

The description explicitly says 'Use for AI-generated or customized components,' providing clear context. It also describes the validation-before-persist workflow, which implies a contrast with validation-only tools, though it does not name an alternative directly.

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 that the tool returns ready-to-paste configuration, implying a read-only operation, but does not explicitly mention side-effect absence, authentication requirements, or error behavior. Still, for a simple retrieval tool, this level is acceptable.

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 purpose, output format, and context of use without any wasted words.

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?

This is a simple tool with one optional enum parameter and no output schema. The description adequately covers what it does, what it returns, and when to use it, making it complete for the given complexity.

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

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

Schema description coverage is 100%: the parameter 'client' already provides a full description ('Target agent client. Omit to get all configs.'). The tool description adds nothing beyond the schema, so a baseline of 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 uses a specific verb ('Returns') and a clear resource ('MCP configuration') with target clients ('Cursor, Claude Code, or Codex'). It distinguishes itself from sibling tools that focus on components, prototypes, or design guidelines.

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

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

Explicitly states when to use: 'Use on the Connect page or when setting up a new project.' It doesn't mention alternatives or exclusions, but for a config-getter there are no overlapping sibling tools, so this is clear enough context.

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 discloses what the tool returns (props, types, defaults, examples, composition patterns, mistakes) and frames it as a read/preflight action to prevent build failures. While it doesn't explicitly state 'no side effects', the verb 'Get' strongly implies a read-only operation, and the description provides meaningful context beyond the 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?

The description is two sentences with no filler. The first sentence front-loads the primary purpose and lists the exact content categories. The second establishes a mandatory usage instruction and provides concrete failure examples. Every part 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 one-parameter retrieval tool with no output schema, the description thoroughly explains what the agent will receive (props, types, defaults, examples, patterns, mistakes) and when to invoke it. The sibling tool context makes its role clear, and the description covers all necessary information for 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 already fully documents the single parameter componentName with an explanatory example, so schema coverage is 100%. The description reinforces that this applies to a single component and explains why the name matters (to avoid wrong props), but it doesn't add new syntactic or format details beyond what the schema provides. 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 uses a specific verb ('Get') and clearly defines the resource: exact props with types and defaults, code examples, composition patterns, and common mistakes for a single @marmoui/ui component. It distinguishes itself from sibling tools like list_components or search_components by focusing on a single component and prescribing the exact detail level.

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 states when to use the tool: REQUIRED before using any component for the first time in a session. It also provides a compelling rationale (prevents hallucinated props that fail at build time). It doesn't enumerate alternatives or when-not-to-use cases, but the mandatory-before-use instruction gives clear context.

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. It discloses the tool's role as a mandatory prerequisite, the need to ask the user about icon library, and the consistency requirement with review_generated_code. It clearly lists what the tool returns, making its behavior transparent. No side effects are relevant for a guidelines read 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 a single dense paragraph but each sentence is purposeful: it front-loads the mandatory call, provides concrete rules and parameters, and gives an explicit instruction to ask the user. No wasted words.

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 two parameters with full schema coverage and no output schema, the description is exceptionally complete: it tells what it returns, how to invoke for specific topics, and how it relates to other tools. It even covers user interaction steps.

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%, but the description adds significant value: it explains the iconLibrary parameter's default, supported values, and the need to pass the same value to review_generated_code. It also clarifies that topic='patterns' returns the generation checklist specifically. This goes beyond the schema's basic parameter descriptions.

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 explicitly states it is the mandatory first call before writing any @marmoui/ui code and returns a generation checklist, critical rules, component patterns, and icon library rules. This clearly defines its purpose and differentiates it from siblings like get_design_md and get_pattern by establishing it as the entry point.

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 instructs when to call (before writing any code), what to do first (ask user about icon library), and how to coordinate with review_generated_code by passing the same iconLibrary value. It also mentions topic='patterns' for a specific checklist, providing clear context for use vs 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 burden, and it adds useful behavioral traits: output is deterministic for a given tenant, and the format can be markdown or JSON. It discloses the 'portable' nature and the fact that it requires an authenticated tenant. It doesn't cover error cases or rate limits, but for a simple read-like generator, this is sufficient.

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 three sentences, each earning its place: the first defines purpose and content, the second explains usage, and the third adds the determinism behavior. It is front-loaded and has zero fluff.

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, no output schema, and no annotations, the description is complete. It covers what it returns, content included, format options, the authentication context, and determinism. An agent has enough to select and invoke it correctly without further clarification.

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 'format' parameter with enum, default, and description, so schema coverage is 100%. The description merely restates what the schema says ('Pass format="markdown" ... or format="json"'), adding no additional meaning or guidance on selection. 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 the action ('Generate a portable DESIGN.md') and the resource/scope ('for the authenticated tenant'), with a specific content list (brand color, type, tokens, component inventory). This distinguishes it from sibling tools like get_design_guidelines or get_tenant_theme, which focus on narrower aspects.

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 clear context—this produces a DESIGN.md that any AI agent can read to generate on-brand UI—implying when it should be used. However, it does not explicitly mention when not to use it or compare it to alternatives like get_tenant_theme or get_design_guidelines, so it misses the full 'when-not' 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. It discloses the return fields, notes the tool is cheap to call, and explains edge-case behavior: 'If gitSha is "unknown" or indexedAt is far in the past, surface that to the user before relying on the data.' This goes beyond basic functionality and provides actionable behavioral guidance.

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 three sentences, each earning its place: what it returns, when to call it, and how to handle stale data. It is concise, front-loaded, and free of any 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?

Given the tool's simplicity (zero params, no output schema), the description covers all necessary context: return fields, usage timing, cost, and edge-case handling. It is complete for an agent to use the tool correctly without further clarification.

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 the baseline is 4. The description does not need to add parameter semantics; it focuses on return values and usage. Since schema coverage is 100% (vacuously), this score 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 the tool's purpose: 'Returns the MCP knowledge version' with specific fields listed (gitSha, indexedAt, componentCount, patternCount, uptimeSeconds). This is a specific verb+resource and is distinct from sibling tools like get_component_info or get_design_guidelines.

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 explicit usage context: 'Call this ONCE per session before generating UI code so you know how fresh the design-system data is.' This tells the agent when to use it, though it does not explicitly mention alternatives or when not to use it. The 'Cheap to call' note further clarifies it is safe to invoke frequently.

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 disclosure. It reveals that the tool returns code plus an inline validation report, has a special interactive flow for app-layouts (asking the user which of 4 layout IDs), and that iconLibrary affects the returned usage note. It does not cover permissions or explicit read-only status, but the 'get' verb implies read-only.

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 front-loaded with the purpose and contains only informative sentences: the pattern list, app-layouts instruction, iconLibrary guidance, and no-argument behavior. It is dense but each sentence earns its place with no wasted words.

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?

Even without an output schema, the description clearly explains return values (code + inline validation report) and covers key usage scenarios: no arguments, app-layouts full-page flow, and icon library handling. It provides sufficient context for correct selection and 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 descriptions cover 100% of parameters, so the baseline is 3. The description adds a slight nuance with 'rewrite the pattern's icons to' which clarifies the effect, but it mostly restates schema details already present in the input schema.

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

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

The description clearly states the tool retrieves a validated composition example for a common UI pattern, lists specific pattern IDs, and distinguishes itself from siblings by emphasizing validation and the app-layouts sub-flow (e.g., generate_component or validate_component_usage). The verb 'get' plus resource and scope is specific and 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?

The description provides explicit usage instructions: call app-layouts first for full pages, pass iconLibrary for correct import source, and call with no arguments to list patterns. It lacks explicit exclusions or named alternative tools, but the context is clear and actionable.

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 behavioral transparency. It discloses the read-only nature (fetch) and the output format, but doesn't mention any prerequisites (e.g., prototype must be shared) or potential edge cases (e.g., empty comments, pagination). This is adequate but not rich.

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 that front-load the action and resource. Every word earns its place, with no filler or redundant 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?

The description is short but covers the core purpose and output type. However, with no output schema and no annotation, details about the exact return shape and the includeResolved parameter are missing. It's adequate for a simple getter but leaves some 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 coverage is only 50%: prototypeId is described, but includeResolved has no description. The tool description does not mention parameters at all, leaving includeResolved's meaning unexplained. The description adds no value over the schema for parameter understanding.

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

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

The description clearly states the tool fetches inline comments from a shared prototype, with a specific verb and resource. It also notes the output formats (structured data and Markdown), which helps distinguish it from sibling tools like get_design_md or get_component_info.

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 second sentence ('Pull into Cursor/Claude to iterate on feedback') provides a concrete use case, but it doesn't explicitly contrast with alternative tools. Since the sibling list includes similar getter tools, more explicit 'use this for prototype feedback, not for design MD' would strengthen the 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?

No annotations are provided, so the description carries the full burden. It discloses the key behavioral trait that authentication is required ('after auth') and specifies exactly what data is returned (theme tokens, CSS variables export, component overrides). It doesn't cover edge cases like empty responses or error conditions, but for a simple read-only getter, this is transparent enough to be genuinely helpful.

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 concise sentences that front-load the purpose and then provide usage context. Every word contributes to the understanding, with no fluff 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 simple tool with no parameters and no output schema, the description provides enough information to understand when to call it and what it returns. It mentions the specific components of the return value (theme tokens, CSS variables, component overrides) which partially compensates for the lack of an output schema. It could be more explicit about possible absence of customization, but it's largely complete for its complexity.

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, and the baseline for zero parameters is 4. The description adds context about what the parameters would imply (the tenant from the auth context) without needing to explain any parameter syntax. No additional parameter documentation is necessary.

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 specific resource (authenticated tenant's customized theme tokens, CSS variables export, and component overrides) and uses a descriptive verb 'Returns'. This distinguishes it from sibling tools like get_design_guidelines or get_design_md, which likely return broader design guidance rather than tenant-specific theme data.

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 clear usage context by stating 'Call after auth to apply tenant-specific styling in generated code.' This indicates when to use the tool (after authentication) and its purpose (styling in generated code). However, it does not explicitly mention alternatives or exclusion cases, so it falls short of a full 5.

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

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

No annotations are present, so the description carries the burden. It transparently states that it lists all components and specifies the returned fields, implying a read-only operation. It doesn't disclose pagination or rate limits, but for a simple listing tool this is sufficient.

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 filler. First sentence states purpose and output, second provides usage guidance. 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 read-only listing tool with two optional filters and no output schema, the description covers purpose, return contents, and usage context. It also flags the sibling alternative. Complete for its complexity.

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 both parameters (status and category) with descriptions. The tool description doesn't add further parameter-level detail, so it meets the baseline for schema-backed parameter 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?

The description uses a specific verb 'List' and identifies the resource '@marmoui/ui components' with output details (names, descriptions, categories, prop counts). It also distinguishes from sibling tools by mentioning when to prefer search_components.

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

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

Explicitly states 'Use to discover what exists' and 'Prefer search_components when you already know the use case', providing clear usage context and an explicit 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, the description carries the full burden. It reveals the return structure ({ valid, errors[], warnings[], suggestedFixes[], iconLibrary }), enumerates five specific error classes, and states that wrong-library icon imports are errors. It also discloses the default iconLibrary and the auto-suggest behavior. This is comprehensive and leaves no safety 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 long but information-dense, using emoji, bold, and a numbered list to guide reading. Every sentence contributes operational insight; there is no filler. It could be slightly trimmed, but the complexity justifies the 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?

Without an output schema, the description compensates by specifying the exact return shape and error categories. It also covers prerequisites (must import from @marmoui/ui), parameter intent, and the conditional loop for calling again. This is a self-contained contract that enables an agent to use the tool correctly and interpret results.

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

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

Schema coverage is 100%, with all three parameters already well-described in the schema. The description largely restates what the schema says (e.g., iconLibrary default and matching get_design_guidelines), adding no new parameter-level meaning. The baseline of 3 applies because the schema does the heavy lifting; the description's value lies in behavioral context, not parameter 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?

The description clearly states the tool's function: it validates TSX/JSX code against @marmoui/ui prop signatures and returns structured feedback. It distinguishes itself from siblings like generate_component (which creates code) and validate_component_usage by being the mandatory post-generation check, with specific error categories. The verb 'validates' and resource '@marmoui/ui' make the purpose 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?

Usage is explicitly prescribed: 'MANDATORY — call this on every piece of code you generate before returning it to the user.' It also provides a clear workflow: fix errors and call again if valid=false, and instructs not to return code with errors. This is stronger than generic guidance, covering when to use the tool and the expected loop.

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 of behavioral disclosure. It does reveal a key behavior: 'returns the 5-8 most relevant components.' However, it does not state whether the tool has side effects, requires authentication, or handles edge cases like no matches. The non-destructive nature of a search is implied but not explicit, and no additional safety or side-effect information is given.

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 long, front-loaded with the core action, and every clause adds value. It is concise without unnecessary elaboration.

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 search tool with 2 params and no output schema, the description covers the core purpose, usage sequence, and a behavioral trait (result count). It does not specify the return format or edge cases, but these are not critical for a discovery tool. Overall, it is sufficiently complete for an agent to invoke it correctly in most scenarios.

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. However, the description adds no meaningful parameter semantics and even introduces potential conflict: it claims 'returns the 5-8 most relevant' while the schema's limit parameter defaults to 10, implying up to 10 results. This lacks clarity and could mislead an agent about result count.

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: 'Search @marmoui/ui by keyword' with concrete examples. It distinguishes itself from sibling tools like list_components and get_component_info by calling itself the 'Preferred discovery tool' and explicitly instructing to call it before get_component_info when uncertain which component to use.

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 usage guidance: 'Call this before `get_component_info` when unsure which component to use.' This establishes a clear workflow and alternative. The phrase 'Preferred discovery tool' further signals when this should be used over other listing or info-gathering 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 full burden. It discloses the return shape ('Returns {valid, issues[]}') and the iconLibrary enforcement behavior ('imports from any other icon library are reported as errors'). It could go further by explicitly stating there are no side effects, but the read-only nature of 'validate' is strongly implied.

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: the first states the core function and return value, the second provides usage guidance. It is front-loaded, efficient, and every sentence earns its place with no 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?

Given the tool's modest complexity, the description covers the purpose, return value, usage guidance, and relationship to a sibling tool. The schema handles parameter details, and no output schema is needed. Nothing meaningful is missing.

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

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

Schema description coverage is 100%, and both parameters already have thorough descriptions (e.g., iconLibrary default and supported values). The main description adds no additional parameter-specific context beyond what's in the schema, so the baseline of 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 states a specific verb ('Validate') and resource ('TSX/JSX snippet against real @marmoui/ui prop signatures'), and clearly differentiates from the sibling tool by naming 'review_generated_code' and explaining the difference. This leaves no ambiguity about what the tool does.

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 instructs when to use this tool ('when validating user-provided or existing code') and when not to ('Prefer review_generated_code for post-generation review'), naming the alternative. This provides direct, actionable guidance.

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