zid_search_users

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

Annotations include readOnlyHint: true and openWorldHint: false, and the description echoes 'Read-only,' which is consistent. It adds behavioral details beyond annotations: the matching logic (partial, case-insensitive, priority for email vs login/display name) and the warning about empty results. This is valuable behavioral disclosure not present in the structured fields.

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 succinct, with four sentences, and front-loads the core purpose. It avoids fluff and each sentence adds value—purpose, read-only, matching logic, and retry caution. No unnecessary words.

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 straightforward search operation with 4 parameters and no output schema. The description covers the essential usage (search criteria, matching behavior, and empty-result handling). It does not discuss pagination or return format, but given the simplicity and presence of limit/offset parameters, it is reasonably complete. The query parameter is well-explained in the schema, so that gap is covered.

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?

The description adds meaning for the 'name' parameter (how matching works), but does not explain 'limit', 'offset', or 'query' (though 'query' is thoroughly documented in the schema with a 25% coverage). Given the low schema description coverage, the description could have provided more context on pagination (limit/offset) and result handling, but it partially compensates for the name field.

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's purpose: 'Search ZIdentity users by name, login name, or email.' It specifies the action (search) and resource (ZIdentity users), and also mentions the search criteria. It is distinct from sibling tools like zid_search_groups and zid_get_user, as it focuses on user search.

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 explicit usage guidance: case-insensitive partial match, behavior for '@' values (email vs login/display name), and a caution against retrying with split keywords or no filter on empty results. It clearly conveys when to use the tool but does not explicitly name alternative tools, though the sibling context makes it obvious.

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