moja.work ui catalog

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

With no annotations, the description carries the full burden and does well: it discloses the return content, the accepted lookup identifiers, and the failure mode when the name is unknown. It does not explicitly state read-only behavior, but 'get' and 'documentation page' strongly imply it.

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 slightly verbose and stylistically eccentric ('cooked machine-fest'), but it front-loads the core purpose and each sentence contributes useful information: return fields, lookup methods, and failure behavior. It could be trimmed without losing meaning, but it is not bloated.

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 annotations and no output schema, the description is remarkably complete. It names the returned fields, explains how to resolve the component, and describes the error response. An agent has enough to call it correctly and interpret 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?

The schema already documents the single parameter as selector, class name, or folder name, and the description adds concrete examples (ui-card, UiCardComponent, card) plus the failure behavior. With 100% schema coverage, this extra context pushes it above baseline.

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 the full documentation page for a single component and enumerates its parts (prose, usage example, input table, truth, api link). It conveys that it targets one component, which distinguishes it from list_components, though it does not explicitly differentiate from get_guide.

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

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

The description implies when to use it — for detailed information about one component — and explains how to identify the component by selector, class name, or folder name. However, it does not explicitly state when to prefer this over get_guide or list_components, leaving the sibling comparison to inference.

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

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

Given there are no annotations or output schema, the description carries the full burden and delivers: it discloses non-authoritative intent ('recommendations, not truth'), provenance and versioning ('written by an agent, stamped with ui version and commit'), and a precedence rule for conflicting sources. This is exactly the kind of contextual behavior an agent cannot infer from the schema and is unusually 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?

The description compresses a lot of useful information into a short space, but the structure is dense, stream-of-consciousness: the two key behavioral branches (with vs. without name) are buried at the end, and the heavy parentheticals hurt scannability. It reads as a single, unbroken prose block rather than clearly front-loading the most important usage distinctions.

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, optional, read-only tool with no annotations or output schema, the description is thorough: it covers both execution modes, the sources of truth, and versioning. The only real gap is that it doesn't detail the exact return format or how errors are surfaced (e.g., an unknown name), but relative to the tool's simple scope, it's nearly complete.

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

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

With 100% schema description coverage, this sits at the baseline of 3, but the description adds genuine meaning by detailing the two behavioral states (with/without the name) and giving concrete value formats (ui-card, burger-menu). It still doesn't expand on the parameter type or provide additional syntax examples, but what's there is helpful and non-redundant.

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?

Clearly identifies the resource (the usage guide) and what it contains ('use for', 'not for', 'instead', 'shown in', house rules), and it's clear an omitted 'name' returns the whole guide while a provided one filters to a component/situation entry. However, it stops short of explicitly naming or routing to its siblings (get_component_doc, list_components), keeping this at a 4 rather than a 5.

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

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

Describes the two parameter modes and the precedence rule ('the page wins') which implies when this tool applies, but never explicitly directs the agent to a specific alternative for a given scenario. The usage context is implied through the 'recommendations, not truth' framing and the family of guide vs. page, but there's no hard 'use X instead' guidance for the sibling tools.

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

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

With no annotations, the description carries the disclosure burden. It explains the output shape by listing all returned fields and adds a notable behavioral detail: every answer includes a provenance line with ui version, commit, and build date. It does not explicitly state that listing is read-only, though the tool name and zero parameters make that highly likely.

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 dense and front-loads the main scope, but it is a single sprawling sentence with nested parentheticals, quoted field names, and an em-dash clause. It could be significantly clearer with a bulleted or separated field list, which would make parsing easier without losing information.

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

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

Without an output schema, the description thoroughly covers the returned fields, the meaning of 'area', the API link, the hasGuide flag, and the provenance line. For a zero-parameter catalog tool this is self-sufficient; an agent knows what the answer will contain and can 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?

The tool has zero parameters and the schema is already complete at 100% coverage, so there is no parameter meaning to supplement. The description instead adds value by explaining what each entry contains, which is the appropriate contribution for a no-parameter tool. Baseline 4 is warranted.

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 returns the complete @mojawork/ui component catalog, enumerating every attribute (selector, aliases, class name, area, brief, API link, hasGuide, provenance). This is a specific verb+resource with a defined scope that separates it from the sibling get_component_doc and get_guide 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 'whole @mojawork/ui shelf' and 'every exported component' phrasing provides clear context: this is the broad catalog/list tool, not a per-component detail or guide lookup. It does not explicitly name alternatives or exclusions, but the intended usage is evident and no conflicting guidance is present.

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