comfyui_search_models

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds meaningful contextual detail beyond annotations: it specifies the external sources (HuggingFace/CivitAI), the return format (JSON with name, URL, size, stats), and the recommended follow-up (download_model). This gives the agent a clear behavioral model, though it does not mention rate limits, authentication, or the fact that only one source is searched at a time (as implied by the 'source' parameter).

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 concise with three sentences: a clear purpose statement, a return-value description, and a usage link to the download tool. It is front-loaded with the primary action and has no redundant filler. Every sentence adds value.

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 5 parameters, good annotations, and an output schema, the description is sufficiently complete. It explains what the tool does, what it returns, and how to use the results (with comfyui_download_model). It does not explain default source behavior or pagination nuances, but those are covered by the schema and annotations. Minor gaps exist, but the overall context is adequate.

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 the parameter descriptions in the schema are clear (query, source, limit, offset, model_type). The tool description does not add much beyond what the schema already provides, except for the mention of 'HuggingFace or CivitAI' which maps to the source enum. Since the schema does the heavy lifting, a baseline score 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 clearly states the tool searches for models on HuggingFace or CivitAI, with a specific verb ('Search') and resource ('models') plus the external platforms. It distinguishes itself from sibling tools like comfyui_list_models (which lists local models) and explicitly states the return output ('JSON with search results including name, download URL, size, and stats'). This is a specific, unambiguous purpose.

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 a clear follow-up action ('Use comfyui_download_model with the URL to install a model'), indicating when this tool is useful in a workflow. However, it does not explicitly state when not to use it or contrast with comfyui_list_models or comfyui_get_model_metadata. The guidance is helpful but lacks explicit exclusions or alternative tool comparisons.

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