keycloak_get_user

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

Annotations declare readOnlyHint=true, so the description does not need to restate that this is a read operation. The description adds one useful behavioral expectation: the result includes custom attributes. It does not disclose behavior for missing users, error responses, or authorization requirements, but for a simple read-only getter the annotation coverage lowers the burden significantly.

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 focused sentence with no filler. The most important information—what is retrieved and a notable return characteristic—is front-loaded, and every word earns its place.

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?

Given the low complexity (two parameters, one required), a read-only annotation, and a clear statement of return scope, the description is sufficiently complete for selecting and invoking the tool. The lack of an output schema is partly mitigated by 'full representation,' though a bit more detail about possible error responses (e.g., user not found) could make it fully complete.

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%, with userId already documented as a UUID rather than a username and with a pointer to keycloak_list_users for discovery. The tool description adds no additional parameter-level meaning beyond stating the result includes custom attributes, so the schema carries the semantic weight and the description meets the baseline.

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 uses a specific verb ('Get') with a clear resource ('one user's full representation') and adds a meaningful detail ('including custom attributes') that distinguishes it from user-subresource tools like keycloak_get_user_groups or keycloak_get_user_sessions. It is unambiguous and immediately tells the agent what this tool returns.

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 clearly positions this as the tool for the complete user object, implying that sibling tools returning specific slices of a user should be used when only those subsets are needed. The userId parameter description further reinforces correct usage by noting the ID must be found via keycloak_list_users, which is direct practical guidance. It does not explicitly list when-not situations, but the contrast with sibling tools is reasonably clear.

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