choerodon_search_users

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'fuzzy search' as a behavioral trait but does not disclose side effects, authentication needs, rate limits, pagination, or error behavior. Important details like what happens with no results or empty input are omitted.

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 sentence, very concise and front-loaded with the action. It is well-structured and avoids unnecessary words. However, it could include a bit more detail without losing conciseness, such as parameter explanations or usage hints.

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?

Despite having an output schema and 3 parameters, the description is minimal. It mentions return fields but does not explain parameters or usage context. The tool is simple, but the description lacks completeness for effective agent invocation, especially regarding the size and project_id parameters.

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%, meaning the description adds no explanation for the parameters. The description only mentions 'by name' which aligns with the required 'name' parameter, but it does not explain the optional 'size' (default 50) or 'project_id' (default ''). The schema itself provides no descriptions, so the tool is poorly documented for parameter usage.

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 action: fuzzy search for Choerodon project members by name. It specifies the return fields (encrypted id, real name, login name). It distinguishes from sibling tools like choerodon_query_issue or choerodon_list_issue, which deal with issues, not users.

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 does not explicitly state when to use this tool versus alternatives. It implies usage for searching users by name, but no guidance on when not to use it or what prerequisites exist. The context of sibling tools indirectly suggests the domain, but explicit guidelines are missing.

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