Watermelon UI

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered structurally. The description adds only the aggregation granularity ('top-level ... across content types') and nothing about cost, caching, or result shape, so it adds modest value beyond structured fields.

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

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

A single front-loaded sentence with no filler. Brief to the point of under-specification, but nothing is wasted.

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

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

For a zero-param read tool with rich annotations but no output schema, the description should at least sketch the return shape; saying 'counts across content types' hints at it but leaves the exact keys/structure unknown. Adequate but with a clear gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. No parameter text is needed or missing.

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

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

States a specific verb (Return) and resource (top-level Watermelon catalog counts), and scopes it to counts across content types, which distinguishes it from sibling list_catalog_entries and list_categories. It is clear but does not explicitly name a sibling it replaces.

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 indication of when to use this versus list_catalog_entries, list_categories, or search, and no prerequisites or exclusions. Usage must be inferred purely from the word 'counts'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that output is source-backed and that block selection is constrained to 'compatible' blocks, which is useful context, but says nothing about return format, determinism, or failure modes.

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, no filler, front-loaded on the verb and the produced artifact. Efficient, though it is arguably too terse to be fully useful rather than merely concise.

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

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

With no output schema and 0% parameter documentation, the description leaves an agent guessing about the input contract and the shape of the returned page plan. For a composition tool whose output drives downstream work, this is incomplete.

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

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

Schema description coverage is 0%, so the description must carry the load and does not. It alludes to sections ('each requested section') but never explains what 'prompt' means, how sections relate to prompt, or the 8-item cap.

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 and artifact: 'Create a source-backed page plan.' It adds the distinguishing mechanism ('selecting compatible Watermelon blocks for each requested section'), which separates it from the catalog browsing siblings. It never names a sibling explicitly, so it falls short of 5.

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

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

There is no statement of when to choose this tool over catalog_summary, get_catalog_entry, or search, nor any prerequisite or exclusion. 'Per requested section' hints at input shape but not at usage 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuine behavioral fact beyond the annotations — that this is a compatibility alias — but says nothing about return shape, and notably fails to name the canonical tool it aliases, which is the most decision-relevant behavior for an alias.

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

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

A single sentence with no wasted words, and the key qualifier ('compatibility alias') is front-loaded. It is appropriately sized, though 'Watermelon entry' is a slightly opaque noun choice.

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 alias tool the safety story is complete via annotations, and no output schema means return values need not be described. But the description omits the two things an agent most needs about an alias: which tool it mirrors and whether it is deprecated in favor of that tool.

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

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

Schema description coverage is 0%, so the description must carry the load; it names both parameters and their roles ('by kind and slug'), which matches the two required fields. However it explains nothing about the kind enum values (components, blocks, dashboards, templates) or slug format, leaving the enum meaning entirely to 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?

It states a verb ('getting') and a resource ('one Watermelon entry'), plus the lookup keys, so the basic operation is inferable. But 'compatibility alias' is vague and the tool is not differentiated from siblings like get_component or list_catalog_entries — an agent cannot tell which tool this actually duplicates or when it is the right one to call.

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 'compatibility alias' weakly implies this exists for backwards compatibility, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent is left to guess whether to prefer this over get_component.

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 annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond that by listing the returned resource contents and the availability condition for installable registry items. It does not cover auth, rate limits, or error behavior, but the annotation bar is lower here.

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 wasted words. The trailing availability condition is slightly awkward but still concise and purposeful.

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

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

With no output schema, the description usefully enumerates the returned artifacts, and the annotations cover safety. However, it leaves both input parameters undocumented and does not clarify sibling selection, so an agent still lacks guidance for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, yet it never mentions the required 'slug' or the enum-valued 'kind' parameter. Terms like 'Watermelon entry' and 'installable registry item' do not map explicitly to either input field.

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 (get) and enumerates concrete return artifacts (preview, dependencies, install command, source files), making the purpose clear. It stops short of explicitly differentiating this tool from the sibling get_catalog_entry or list_catalog_entries.

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

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

It gives only an availability condition ('when an installable registry item is available') but does not explain when to choose this tool over siblings like get_catalog_entry or search. No when-not guidance or alternative routing is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered by structured data. The description adds only the output cardinality (3-6 options), a modest but real piece of behavioral context, with no contradiction.

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

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

A single front-loaded sentence with no filler; the key action and the exploratory intent come first. It is well-sized, though it uses its brevity at the cost of parameter explanation.

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

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

No output schema exists, but the description at least communicates the return cardinality and the non-committal exploratory role. With three parameters at 0% schema coverage, the omission of any 'kinds' or 'prompt' semantics leaves a meaningful gap for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it explains nothing about the 'prompt' or 'kinds' parameters. Its only numeric detail (3-6) merely restates the schema's own minimum/maximum on 'limit', adding no meaning beyond structured fields.

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 gives a specific verb ('Return') and resource ('visually relevant Watermelon UI options') and even quantifies the output ('3-6'), so the agent knows what it gets back. It does not explicitly differentiate itself from siblings like search or list_catalog_entries, which is the only thing keeping it from 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?

The phrase 'before choosing an implementation' implies the tool is a preliminary exploration step, which is useful implied guidance. However, it names no alternatives and gives no explicit when/when-not conditions, so an agent must infer how this differs from search or get_component.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior. The description adds that this is a compatibility alias, which is useful behavioral context, but it does not disclose return format, pagination, or alias semantics.

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 single sentence is short and front-loads the listing purpose, but it is under-specified rather than genuinely efficient; it omits information an agent needs to invoke the tool correctly.

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 four-parameter tool with no schema descriptions and no output schema, the description is too thin. Annotations cover safety, but the description does not compensate for missing parameter and return-value context.

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% for all four parameters. The description mentions 'by kind' and thus adds minimal meaning for the required kind parameter, but says nothing about limit, query, category, or the kind enum values.

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

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

States a specific verb 'listing' and resource 'Watermelon entries' with the kind scoping, but 'Compatibility alias' is unexplained and it does not differentiate from siblings like get_catalog_entry or list_categories.

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 when-to-use, when-not-to-use, or alternatives are given. The phrase 'Compatibility alias' hints at a use case but does not say when an agent should choose it over search or get_catalog_entry.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, and closed-world, so the safety profile is well covered. The description adds that returned entry counts are 'accurate,' hinting the counts are reliable totals rather than estimates, but it does not describe output shape or pagination.

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

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

A single front-loaded sentence with no filler; the optional filter is stated last where it belongs. Very little is wasted, though the word 'accurate' is slightly editorial.

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-optional-parameter read tool with rich annotations and no output schema, this covers purpose, scope, and return content adequately. Only the relationship to overlapping list/summary siblings is left unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the load: it explains that 'kind' scopes results to a single catalog kind and that it is optional. The enum values themselves (components, blocks, templates, etc.) are self-describing, leaving little ambiguity.

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

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

States a specific verb and resource ('List Watermelon UI categories') plus the payload ('accurate entry counts') and the optional scope ('one catalog kind'). It is clear what the tool does, but it does not explicitly distinguish itself from close siblings like catalog_summary or list_catalog_entries, so the agent must infer the boundary.

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?

'Optionally for one catalog kind' implies when the filter is useful, but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as list_catalog_entries or catalog_summary, which overlap in the sibling set.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world (openWorldHint=false), so the safety profile is fully covered without the description. The description adds the scope of the corpus searched ('complete catalog across components, animated components, blocks, dashboards, and templates'), but says nothing about ranking, result ordering, or truncation behavior for a search 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?

One front-loaded sentence, verb first, no filler or repetition. It is tight, though the tightness comes partly from omitting information an agent would need rather than from ruthless editing.

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 search tool with four parameters, no output schema, and only 25% schema coverage, the description should clarify result shape, ordering, and the undocumented 'category' parameter. Annotations cover safety, but the missing behavioral and parameter context leaves real gaps for correct invocation.

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

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

Schema description coverage is only 25% — just 'query' is documented, and its description already supplies the natural-language example. The description merely re-lists the kind values that the schema enum already enumerates, and adds nothing about 'category' or about how 'limit' interacts with result ranking.

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

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

Specific verb+resource ('Search the complete Watermelon UI catalog') with the searchable domains enumerated, so the agent knows it is a search tool rather than a fetch tool. However, it never contrasts itself with the closest siblings, list_catalog_entries and catalog_summary, which also surface catalog content.

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 says what it searches but never states when to choose it over list_catalog_entries, get_inspiration, or catalog_summary. No prerequisites, no exclusions, no query-phrasing guidance beyond what the schema already carries.

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