dsh_plugin_search

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

No annotations are provided, so the description carries the transparency burden. It discloses that the search operates on the 'cached' catalog, implying a read-only operation that may not reflect the latest live data. However, it does not explicitly confirm no side effects, nor describe return format or pagination behavior, leaving some behavioral aspects implicit.

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, front-loaded with the core action and resource. Every word earns its place, with no filler or repetition of schema details.

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 a simple search, so the description is minimally adequate. It relies on dsh_plugin_list for filter details and does not mention output shape or pagination, which are left implicit. With no output schema and no annotations, a bit more context would be warranted, but it does cover the essentials.

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 low (only 'query' has a description), and the description compensates somewhat by explaining 'free-text query' and referring to dsh_plugin_list for filter semantics. However, limit, language, and minStars are not directly explained, relying on the sibling reference for full 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 'Search the cached dsh-plugin catalog by free-text query,' providing a specific verb, resource, and query mode. It distinguishes from siblings like dsh_plugin_list and dsh_plugin_get by emphasizing free-text search, and the reference to dsh_plugin_list further clarifies its niche.

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 provides clear context: use this for free-text querying, and the filters are identical to dsh_plugin_list. However, it does not explicitly state when to prefer this over dsh_plugin_list (e.g., broad search vs. browsing), so it lacks explicit exclusions or alternative guidance.

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