keycloak_list_users

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

With readOnlyHint=true covering the mutation-safety profile, the description adds genuinely behavioral context: the match semantics of each mode (loose infix vs. exact pair vs. attribute key:value) describe how results are selected, not just what parameters exist. It doesn't disclose output shape or how multiple filters combine, but the annotation lowers the bar and the mode semantics clear it.

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, roughly 42 words, with the core purpose front-loaded and the mode breakdown delivered as a single efficient clause. Every phrase earns its place; there is no filler, redundancy, or preamble.

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 complex 14-parameter tool with no output schema, the description covers the primary decision axis (which search mode to use) while the schema's rich per-parameter descriptions handle max bounds, briefRepresentation, and the context-flooding warning. The remaining gaps — implicit AND semantics across filters and unspecified return shape — are predictable for a list tool and partially bounded by the max default, making this adequate but not exhaustive.

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 79%, just under the 80% high-coverage threshold, so the description bears some compensating weight. It adds cross-parameter semantics the schema lacks — grouping parameters into three search strategies and clarifying that `username`/`email` are only precise when paired with `exact`. The few undocumented params (firstName, lastName, emailVerified) are self-explanatory by name, so the gap is minor.

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?

"Search users in a realm" states a specific verb and resource in six words. The three search modes (search / username-email+exact / q) make clear this is a multi-record lookup tool, distinguishing it from siblings like keycloak_get_user (single user fetch) and keycloak_count_users (aggregation only) without needing to open their schemas.

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 maps concrete lookup scenarios to parameter choices: loose match across name/username/email via `search`, precise lookup via `username`/`email` paired with `exact`, and attribute filtering via `q` — noting q is the only way to filter on attributes. It provides clear decision context but stops short of naming sibling alternatives or stating explicit when-not-to-use conditions, which keeps it from a 5.

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