search_ui

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

With no annotations at all, the description carries the full burden, and it does disclose the important behavioral fact that result type varies by source (screens vs. apps). It says nothing about pagination behavior, result limits, or rate constraints, which matter for a search tool, so the disclosure is partial rather than complete.

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

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

A single dense sentence with the search action front-loaded and the downstream tooling named last, in the order an agent needs it. It is packed tight with semicolons but nothing is wasted or redundant.

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 three-parameter, no-annotation, no-output-schema tool, the description covers the crucial unknowns: what the tool operates on, how output shape depends on source, and where the results feed next. An agent can invoke it correctly armed only with this text plus the 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?

Schema coverage is 67%, and the description compensates by grouping the enum values by return kind — refero-*/dribbble yield screens, screensdesign and mobbin-* yield apps — which adds real meaning the schema enum list alone does not convey. The page parameter is documented in the schema and needs no further explanation.

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 ("Search a UI library source") and immediately characterizes what comes back, which is unusual and useful. It does not distinguish itself from sibling library_search or ui_sources, so an agent cannot tell from the description alone which of the two search-ish tools applies.

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?

Gives strong downstream routing — "pass an app's appId to get_ui_screens or download_ui" — so the agent knows what to do after a result. However, there is no statement of when to choose search_ui over library_search or ui_sources, and no prerequisites or exclusions.

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