ugreen_search

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

The annotations already cover the safety profile (read-only, idempotent, non-destructive, open-world), so the description correctly spends its words elsewhere: default recursion, the fact that results can be paginated, the task_id/next_offset return fields, and an explicit warning not to treat a single response as the full result set. That last warning is real behavioral context an agent would otherwise miss, though nothing is said about result ordering or limits.

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?

Two sentences, front-loaded with the core action, then the pagination rule. No filler and no repetition of annotation content.

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 does well to disclose the task_id/next_offset continuation contract. However, three of five input parameters remain undocumented and there is no mention of what a result entry looks like or how limit interacts with pagination, leaving gaps for an agent assembling a paged search.

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% across 5 parameters, so the description alone must carry meaning. It clarifies the semantics of query ('按名称') and recursive ('默认递归'), but says nothing about path, limit, or suffix, leaving three parameters with no explanation anywhere.

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 names a specific verb and resource ('按名称搜索 NAS 文件/目录') plus scope (recursive by default), and it explicitly separates this tool from the sibling ugreen_search_results by assigning that tool the continuation role. An agent can tell which tool starts a search and which resumes one without opening either schema.

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 gives a clear conditional handoff: when the response carries task_id and next_offset, switch to ugreen_search_results. It does not say when to prefer this over other read siblings such as ugreen_list_files or ugreen_file_stat, so the guidance is strong but incomplete.

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