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

readOnlyHint=true already covers the safety profile; the description adds meaningful context beyond it: the tool verifies live credential validity, reports realm/account identity and write capability, and exposes remediation details ('exactly what to set'). It stops short of disclosing the failure mode when the Keycloak server itself is unreachable, which would make it fully transparent.

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 with zero filler: the first front-loads the verb, resource, and enumerated report contents; the second adds the usage trigger and diagnostic interpretation. Every clause earns its place, and the key discriminating information appears first.

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 0-parameter, readOnly-annotated diagnostics tool with no output schema, the description covers what it reports, when to call it, and how to interpret its availability. Nothing an agent needs to invoke it correctly is missing.

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 tool has zero parameters, so per the rubric the baseline of 4 applies — there is nothing the description must explain. The description correctly invents no parameters or flags, and the 100% schema coverage is trivially vacuous for an empty properties object.

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 opens with a specific verb and resource ('Report whether this server has working Keycloak credentials') and enumerates the exact outputs: realm, acting account, write-enablement, and remediation guidance. It distinguishes itself from all 47 siblings, notably keycloak_whoami (current user identity), since no other tool reports auth configuration health.

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?

Gives an explicit trigger condition: 'Call this first when a tool you expected is not listed.' It also teaches the agent how to interpret the result — an absent tool means missing configuration rather than a bug — which directly selects this diagnostic over the get/list siblings and guides the next action.

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

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

The readOnlyHint annotation already establishes the tool is safe, and the description adds one useful behavioral detail: it returns a count without fetching user objects. No further behavioral context (return shape, large-dataset behavior) is disclosed, and nothing contradicts the annotation.

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?

Nine words, front-loaded with verb and object, and the differentiating clause 'without fetching them' earns its place. There is no filler or repetition of schema contents.

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 read-only count operation, the description plus the heavily documented schema is nearly sufficient: the contrast with user-listing tools is clear and count semantics are self-evident. It stops short of perfect because it relies on inference for the return format and never explicitly names keycloak_list_users as the alternative.

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 70%, so most parameters are already documented in the schema. The description contributes only the generic phrase 'matching a filter,' adding no meaning about individual parameters such as q, email, or exact, and it does not compensate for the three undocumented fields (lastName, firstName, emailVerified).

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 ('Count') with a specific resource ('users') and scope ('matching a filter'). The clause 'without fetching them' directly distinguishes it from siblings like keycloak_list_users and keycloak_get_user that retrieve user records.

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 implies the use case: pick this tool when the agent needs a count rather than the actual user data. However, it never names an alternative explicitly or states when not to use it, leaving the agent to infer the boundary with keycloak_list_users from the sibling list alone.

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

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

Annotations already mark the tool readOnlyHint=true. The description adds useful behavioral context beyond that by stating the evaluation happens 'without logging anyone in' and that it simulates what token a client would issue. This clarifies the non-destructive, simulation-like nature of the operation and does not contradict the annotation.

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 tight sentences with no filler. The first sentence states what the tool does, and the second sentence explains the practical use case. Information is efficiently front-loaded.

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 no output schema, the description still communicates that the tool returns an access token/JWT and that it is for diagnosing claims. It does not detail optional parameter interactions, but the schema covers those. Overall, the description is complete enough for a read-only evaluation tool.

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 75%, so most parameter meaning is already in the schema. The description does not add further parameter-level detail, but the required clientUuid is self-explanatory and the remaining optional parameters are documented in the input schema.

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 states a specific verb and resource: 'Generate the access token a client would actually issue.' It also frames the tool's diagnostic purpose ('why is this claim missing from my JWT?'), which helps an agent distinguish it from the many read-only Keycloak sibling tools.

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 usage context: use this when investigating missing JWT claims. It does not explicitly name alternatives or state when not to use it, but the diagnostic framing is enough to route an agent appropriately.

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

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

The readOnlyHint annotation already signals this is a safe read operation. The description adds useful behavioral context beyond that by explaining the returned steps are ordered and encoding execution requirements, plus interpreting their meaning in login flows. No contradiction with the annotation exists.

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 two tight sentences: the first states the operation and output, the second gives the practical significance. There is no redundant filler or repetition of schema details.

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 present, the description adequately conveys what the tool returns: ordered steps with their requirement types. The parameter schema covers the inputs, annotations cover safety, and the description covers the result semantics and real-world relevance, making the definition complete for an agent.

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 input schema already documents both parameters, including the realm default and flowAlias examples. The description adds little parameter-level detail beyond framing flowAlias as selecting a flow, so it meets the baseline for full schema coverage but does not elevate it.

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') and resource ('ordered steps inside a flow') and specifies the key output property: whether each step is REQUIRED, ALTERNATIVE, CONDITIONAL or DISABLED. This clearly separates it from sibling tools like keycloak_list_authentication_flows, which operate on the flows themselves rather than their internal steps.

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 clear context for when to use this tool: to understand what a user is actually asked for during login (password, OTP, etc.). It does not explicitly name sibling alternatives or state when not to use them, so it falls just short of full use/alternative guidance.

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

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

The readOnlyHint annotation already signals no mutation, and the description adds meaningful behavior beyond it: the secret is redacted, and the response includes flows, redirect URIs, web origins, and attributes. It does not discuss errors or response shape, but for a simple read action the added transparency is strong.

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 with no filler, and the most important distinction (secret redaction, use the sibling tool) is placed near the end without wasted wording. Every sentence contributes value.

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 only two parameters, a rich schema for clientUuid, and the readOnlyHint annotation, the description covers what the tool returns, what is omitted (secret), and where to go for that omitted piece. No output schema is present, but the description gives enough for an agent to call and interpret the result.

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%, so the schema fully documents both parameters. The description itself adds no extra parameter-level meaning, making the baseline 3 appropriate.

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 states a specific verb ('Get') and resource ('a client's full configuration'), and names the exact content areas: flows, redirect URIs, web origins, and attributes including token lifespans. It also distinguishes itself from keycloak_get_client_secret by explicitly noting the secret is redacted here.

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 when/not: use this tool for the full client configuration; if the secret is needed, use keycloak_get_client_secret instead. This is an explicit alternative and a clear boundary for the most likely confusion with a sibling tool.

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

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

The readOnlyHint annotation already communicates safety. The description adds useful behavioral context by clarifying that default scopes are always applied while optional scopes are applied only on request. However, it does not describe the response shape or any other operational behavior, so it adds only moderate value beyond the annotations.

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 that front-loads the main purpose and immediately communicates the key distinction between default and optional scopes. Every word contributes to the agent's understanding, with no filler or repetition.

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 simple read-only getter, the description conveys the core purpose and output concept. However, without an output schema, more detail about the response structure would help, and clientUuid remains ambiguous to an agent unfamiliar with Keycloak conventions. It is adequate but not 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 only 50%. The description does not explain clientUuid beyond the parameter name or add semantics to either parameter. The realm parameter benefits from its schema description, but clientUuid is left underdocumented, and the tool description does not compensate for that gap.

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 ('Show') and a resource ('client scopes assigned to a client'), and adds the distinguishing detail that output is split into default and optional scopes. This makes its purpose clear and distinguishes it from sibling tools like keycloak_list_client_scopes or keycloak_evaluate_client_scopes.

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 context is clear: use this when you need to know which scopes are assigned to a client, including the default vs optional distinction. It does not explicitly mention alternatives or when not to use it, so it stops short of a 5, but it gives enough contextual guidance for an agent to select it.

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

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

The annotations already declare readOnlyHint=true, so the read-only behavior is covered by structured metadata. The description adds useful context by stating the output is a ready-to-use adapter config with credentials, but it does not disclose additional behavioral details like response format or whether credentials are sensitive. This is acceptable given the annotations cover the safety profile.

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 two sentences with no filler. The main function is front-loaded, the output format is named, and the added use-case sentence 'Handy for wiring an app up to this client' earns its place by giving the agent actionable context.

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 simple read operation with one required parameter and complete schema documentation. There is no output schema, but the description explains what the output is and what it contains. The combination of description, schema, and readOnly annotation is sufficient for an agent to select and invoke this tool correctly.

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%, so the schema already documents both `realm` and `clientUuid`. The description does not add parameter-level detail, but it does not need to because the schema's parameter descriptions are already complete, including the warning that `clientUuid` is the UUID and not the human-facing clientId.

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 specifies a concrete verb ('Get'), a clear resource ('ready-to-use adapter config (keycloak.json)'), and the contents of that resource (issuer URL, realm, credentials). This is distinct from sibling tools like keycloak_get_client or keycloak_get_client_secret, and the phrase 'adapter config' uniquely identifies this tool's purpose without ambiguity.

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 phrase 'Handy for wiring an app up to this client' provides a clear use-case context, implying when this tool is appropriate. However, it does not explicitly distinguish it from alternatives such as keycloak_get_client_secret or state when it should not be used, so the guidance remains implicit rather than explicit.

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

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

The readOnlyHint annotation already covers the safety profile. The description adds the useful detail that protocol mappers are included in the result, but it does not disclose behavior on missing scope IDs, format of response, or any other operational traits.

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, short, front-loaded sentence with no wasted words. Every part adds useful information about the tool's purpose and return 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?

For a simple, read-only, two-parameter retrieval tool, the description is sufficiently complete. It names the resource and the expected included content, and the lack of an output schema is offset by the simplicity of the operation.

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%, so the schema already documents both parameters adequately. The description does not add extra parameter-level meaning beyond implying that scopeId selects the specific scope.

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 specifies a clear verb ('Get'), a precise resource ('one client scope'), and adds a distinguishing detail ('with its protocol mappers'). This clearly separates it from list-oriented siblings like keycloak_list_client_scopes and from other getters.

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 implies usage when a single client scope is needed by UUID, but it does not explicitly state when to choose this tool over alternatives such as keycloak_list_client_scopes. No when-not or alternative guidance is provided.

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

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

Annotations only provide readOnlyHint=true, so the burden is on the description to disclose risk. It does so clearly: the secret is a live credential, will surface in the conversation, requires elevated permission, and can be gated behind an environment variable. There is no contradiction with the read-only annotation.

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 deliver high-value information with no filler. The most safety-critical fact ('CURRENT SECRET IN PLAIN TEXT') is front-loaded, followed by the exposure warning and permission requirement.

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 simple two-parameter read tool with no output schema, the description is enough to select and invoke it correctly: it states what the tool returns, the risk of using it, the permission needed, and a mitigation option. No critical information is missing.

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 input schema already documents both parameters at 100% coverage, including the crucial clientUuid distinction from clientId and the suggestion to get it from keycloak_list_clients. The description itself adds no parameter-level meaning, so the schema carries the weight; baseline 3 applies.

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 ('Get'), a specific resource ('confidential client's current secret'), and explicitly notes it is 'IN PLAIN TEXT.' Among the many keycloak_* siblings, this unambiguously identifies the secret-retrieval operation and distinguishes it from generic client getters.

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?

It states the required permission ('Requires manage-clients') and gives a notable warning about the credential appearing in conversation. It also hints at a deployment-level safeguard (KEYCLOAK_ALLOW_WRITES), but it does not explicitly name sibling alternatives or state when not to use the tool.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds a valuable interpretation: the returned user is where admin roles are assigned, which helps the agent understand the result's meaning. However, it doesn't disclose response format, pagination (unlikely for a single object), or behavior when no service account exists. With read-only annotation, the bar is lower, but the description still leaves some behavioral gaps.

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, no filler. The action is stated first, followed by the conceptual why. The role-assignment context earns its place because it explains the tool's purpose and informs the caller of the result's significance.

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 read-only getter with one required parameter and a fully described schema, this is nearly complete. The description states what is returned (a service-account user) and why it matters. There is no output schema, but the return object is implied by the resource type. Minor gaps: no mention of error conditions (e.g., missing service account) or explicit response shape, but these are not critical for a simple fetch by UUID.

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%: both parameters are fully documented in the input schema. The clientUuid schema description is exceptionally clear (noting it's the `id` field, not clientId, and pointing to keycloak_list_clients). The tool description itself adds no parameter-specific meaning, and with high schema coverage, the baseline of 3 is appropriate.

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 opens with a specific verb and resource: 'Get the service-account user backing a client.' It immediately distinguishes this tool from siblings by focusing on the service-account user (no other sibling mentions this), and it adds interpretive value by explaining that this user carries the client's admin roles. This gives an agent both the action and the domain significance.

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 clear usage context: 'this is the way to check what a client can actually do.' This implies the when-to-use case (determining client permissions) without naming a specific alternative or exclusion condition. It satisfies the 'clear context, no exclusions' level rather than the explicit when/alternatives level.

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

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

The readOnlyHint annotation already signals a safe read operation, so the description does not need to repeat that. The description adds useful specificity about counting active sessions rather than listing them, but it does not disclose details like whether the count includes offline sessions or how the result is returned.

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 concise sentence that communicates the core operation without any filler or redundant information. It is appropriately front-loaded and easy to parse.

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 simple read-only counting operation with only two parameters, the description and schema together provide enough context for an agent to call it. The output is not documented, but for a count operation this is a minor gap given the simplicity and the readOnlyHint annotation.

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 schema describes the realm parameter but gives no description for clientUuid. The description's 'one client' helps clarify that clientUuid selects the target client, but it adds minimal meaning beyond that and does not fully compensate for the missing clientUuid documentation.

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 states a specific verb ('Count') and resource ('active sessions for one client'), which clearly identifies the operation. It also distinguishes itself from sibling tools like keycloak_get_client_sessions, which would list sessions rather than count them.

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 phrase 'for one client' implies the tool is used when a client-level session count is needed, as opposed to realm-wide statistics. However, it does not explicitly mention alternatives such as keycloak_get_realm_session_stats or keycloak_get_client_sessions, nor does it state when not to use this tool.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds the 'active' qualifier, indicating it returns only live sessions, but it does not disclose pagination behavior or output shape beyond what the schema provides.

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?

A single sentence with no filler or redundancy. It communicates the core operation immediately and efficiently.

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 read-only list operation with a fully documented parameter schema, the description is sufficient to guide invocation. The main gap is the lack of any stated return-value shape, but that is somewhat mitigated by the simple 'list sessions' semantics and readOnlyHint.

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?

All four parameters have schema descriptions, so the baseline is 3. The description adds no extra parameter semantics beyond reinforcing clientUuid as the scoping identifier.

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 states a specific verb and resource: 'List the active user sessions for one client.' It clearly differentiates the client-scoped focus from user-focused tools like keycloak_get_user_sessions, though it does not explicitly name any sibling alternative.

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 wording implies this tool is for retrieving active sessions for a single client, but it provides no explicit when-to-use guidance, exclusions, or alternatives. Given the large sibling set, more direct routing would be helpful.

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

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

The readOnlyHint=true annotation already establishes the safety profile, and the description adds useful context about what the config response covers (enabled flag, event types, retention). However, it does not disclose the return format or value units, and the diagnostic framing adds context rather than deep behavioral detail. Consistent with the annotated-read baseline, 3 is appropriate.

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 with zero waste: the first states the tool's purpose and content, the second provides diagnostic guidance. Both sentences earn their place, and the key information is front-loaded.

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 low-complexity tool — one optional parameter, no output schema, no nested objects, read-only annotation — the description is nearly complete. The only gap is the lack of any indication of the response shape or retention value format, which is minor for a simple diagnostic config read.

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% — the 'realm' parameter is already described in the schema ('Defaults to the server's configured realm (KEYCLOAK_REALM)'). The description adds no additional parameter nuance, so the baseline 3 applies.

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-resource pairing: 'Show whether event logging is enabled for the realm, which event types are recorded, and how long they are kept.' It enumerates exactly what the tool reveals (enabled state, event types, retention duration) and clearly distinguishes itself from the event-listing siblings (keycloak_list_events, keycloak_list_admin_event) by covering configuration rather than event data.

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?

'Check this first if the event tools come back empty' provides an explicit, actionable trigger condition that routes the agent to this tool as a diagnostic first step. It falls short of naming the specific alternative tools or stating when not to use it, but the context is clear enough for a competent agent to select correctly.

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

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

Annotations already declare readOnlyHint=true, so the safe-read behavior is known. The description adds that the result includes attributes and subgroups, which is useful context, but it does not describe response shape, error behavior, or why subgroups are included in this call rather than a separate endpoint.

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 that states the operation, the target resource, and the return contents. It contains no filler, repetition, or unnecessary details, and the key purpose is front-loaded.

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 simple read operation with full schema coverage and a readOnly annotation, the description is nearly complete. It conveys what the response includes ('attributes and subgroups'), and the schema covers the parameters. The only minor gap is that it does not mention pagination or the exact representation of subgroups, but the tool's simplicity keeps this from being a major deficiency.

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%, and the schema already clarifies that groupId must be the UUID (`id` field) not name/path, and that realm defaults to KEYCLOAK_REALM. The description adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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 states a specific verb ('Get') and resource ('one group'), and clarifies the return scope ('with its attributes and subgroups'). This distinguishes it from listing tools like keycloak_list_groups, though it does not explicitly name sibling alternatives.

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 implies use when you need a single group's details, but it provides no explicit guidance about when to prefer this tool over siblings such as keycloak_get_group_members, keycloak_get_group_role_mappings, or keycloak_get_user_groups. The intended use is inferable but not spelled out.

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

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

The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds the semantic scope 'users in a group' but does not disclose behavioral details such as pagination behavior, the effect of briefRepresentation, or whether only direct members are returned. These are left to the input schema rather than the description.

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, short sentence that is front-loaded and precise. There is no filler or redundant wording; it contains exactly the necessary semantic 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?

For a simple read-only listing tool, the description plus a fully described 5-parameter schema and readOnlyHint annotation cover most operational needs. The main gap is that it does not describe return shape or direct-members semantics, and there is no output schema to compensate, but overall the definition is sufficiently 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%, and the schema already provides rich descriptions for all five parameters including groupId UUID semantics, max/first pagination, realm defaulting, and briefRepresentation guidance. The description adds no parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate.

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 'List the users in a group' uses a specific verb and resource, and directly conveys that this tool returns group members. It is clearly distinct from sibling tools like keycloak_get_user_groups, keycloak_get_group_role_mappings, and keycloak_list_users without needing to open any 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 implies the usage scenario: call this tool when you have a groupId and want the users in that group. However, it does not explicitly mention alternatives, exclusions, or when-not-to-use guidance relative to the many sibling list tools.

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

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

The readOnlyHint annotation already covers the non-mutating nature, so the bar is lower. The description adds a useful semantic fact about role inheritance, but it does not disclose the response shape, whether both realm and client roles are included, or how the result is structured.

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 short sentences with no filler. The core purpose is front-loaded, and the inheritance consequence adds value without excess length.

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 simple read-only fetch with fully documented parameters and a readOnlyHint, the description is largely sufficient. It could be slightly more complete by noting whether the result separates realm roles from client roles, but this is a minor gap given the simplicity of the operation.

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 schema has 100% parameter coverage and already explains that groupId is a UUID, not a name or path. The description adds no parameter-level detail, which is acceptable because the schema fully documents the parameters.

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 begins with a specific verb and resource: 'Get the roles mapped to a group.' It clearly distinguishes this from user-level role mapping tools in the sibling list. The added sentence about inheritance makes the purpose even more unambiguous.

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 no explicit guidance on when to use this tool instead of related tools like keycloak_get_user_role_mappings or keycloak_get_role_composites. It implies relevance for group-based inherited roles but does not name alternatives or state when not to use it.

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

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

The readOnlyHint annotation already covers the non-destructive nature; the description adds value by disclosing the client secret is redacted and by summarizing the response contents. This tells the agent what kind of data to expect beyond what annotations alone convey. It does not contradict any annotation.

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, dense sentence that front-loads the action and resource, lists concrete config categories, and adds the redaction caveat without unnecessary elaboration. Every word contributes useful information.

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 simple 2-parameter read operation with a read-only annotation and well-documented schema, the description is largely sufficient. It tells the agent what the tool returns (full config, key categories, redacted secret). Minor gaps include error behavior for unknown aliases and any permission requirements, but these do not significantly hinder correct invocation.

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?

Both parameters are fully described in the input schema: alias is explained as the unique identity provider key, and realm is noted as defaulting to the server's configured realm. The tool description adds no parameter-specific semantics, so the baseline 3 is appropriate given 100% schema description coverage.

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 states a clear, specific operation: retrieving one identity provider's full config, and enumerates what the config contains (endpoints, trust settings, sync mode). The singular 'one' clearly differentiates this from the sibling list_identity_providers tool. It also notes the client secret is redacted, adding an important purpose-level detail.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The description does not mention that this is the tool to use when a single identity provider's config is needed as opposed to listing providers, nor does it identify any alternative tool.

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

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

The annotations already declare readOnlyHint=true, and the description's 'Get' is consistent with that. The description adds useful scope context by enumerating the configuration areas returned, but it does not disclose additional behavioral details such as response shape or potential error conditions; with the annotation covering safety, this is adequate but not rich.

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, front-loaded sentence with no filler. It immediately states the operation and resource, then uses a colon-delimited list to efficiently convey scope without redundancy.

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 read-only getter with one optional parameter and no output schema, the description provides enough context about what the result covers. It names several key configuration areas, making the tool's purpose clear for selection and invocation, though it does not describe the exact return format.

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?

There is only one parameter, 'realm', and the schema already fully describes it with a clear description and a default behavior. The tool description adds no additional parameter semantics, but the baseline of 3 applies because the schema carries the complete burden.

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 opens with a specific verb and resource: 'Get a realm's full configuration,' and it lists concrete configuration categories such as token lifespans, login/registration settings, password policy, SSO session timeouts, and flow bindings. The word 'full' helps distinguish it from narrower sibling tools like keycloak_get_realm_flow_bindings, though it does not explicitly name that alternative.

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 implies this tool is the broad getter for an entire realm's configuration, which is useful context when deciding among the many get_* sibling tools. However, it does not explicitly state when to use this tool versus a more specific tool like keycloak_get_realm_flow_bindings or keycloak_get_realm_session_stats, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint=true, and the description's 'Show' is consistent with a safe read operation. It adds useful context about which entry points are covered but does not disclose output shape or pagination; no annotation contradiction.

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?

Single sentence with no filler. The entry-point examples are high-value and make the behavior concrete without bloating the text.

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 one-parameter read-only tool with a simple purpose and no output schema, the description gives enough to invoke it correctly. It doesn't explicitly describe the return structure, but the examples of entry points map the output domain adequately.

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 only parameter, realm, is fully documented in the schema with 100% coverage, including its default to KEYCLOAK_REALM. The description adds nothing about parameters, so it relies on the schema's sufficient description.

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 'Show', names the resource (flow bindings for realm authentication entry points), and gives concrete examples. This clearly separates it from sibling flow tools like list_authentication_flows.

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?

It clearly conveys that this tool is the source for authentication-flow-to-entry-point bindings, but it never explicitly states when to prefer it over siblings or offers exclusions. Usage context is implied rather than stated.

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

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

The annotations already declare readOnlyHint=true, so the read-only safety profile is covered. The description adds that the result includes attributes and composite flag, but it does not disclose not-found behavior, authorization requirements, or how the composite flag is represented. With annotations carrying the safety burden, a 3 is appropriate.

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?

One efficient sentence with no filler. The verb, resource, addressing key, and key output traits are all front-loaded, and every phrase 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, complete parameter schema, and readOnlyHint annotation, the description is nearly sufficient. It identifies the resource, lookup method, and main returned fields, though it omits explicit not-found/error behavior and a full return shape since there is no output schema.

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%, so both realm and roleName are already documented. The description reinforces that roles are addressed by name, matching roleName's schema text, but it does not add format, defaulting, or interaction details beyond what the schema provides.

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 states a specific verb ('Get'), a single resource ('one realm role'), and the lookup key ('by name'). It also previews the returned content ('attributes and composite flag'), which helps distinguish it from list_realm_roles and get_role_composites.

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?

Usage is implied: use this when you need a single realm role by name. However, it does not explicitly contrast with sibling tools like keycloak_list_realm_roles for enumeration or keycloak_get_role_composites for a separate composites endpoint, leaving some selection work to the agent.

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

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

Annotations declare readOnlyHint=true, and the description is consistent with that. However, the description adds no behavioral detail beyond purpose—no mention of pagination behavior, return format, or whether membership is direct vs. effective. It does not contradict the annotations.

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 efficient sentence with a clarifying parenthetical. It is front-loaded and contains no filler.

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 read-only list tool, the purpose and pagination params are documented, and annotations cover safety. However, the description does not specify the output format or whether membership is direct vs. inherited, and it lacks usage differentiation from siblings. This is acceptable but leaves some gaps.

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 75%; roleName lacks a description, but the tool description clarifies that it identifies the role whose members are listed. The other parameters (max, first, realm) are already described in the schema. The description adds minimal parameter-level meaning beyond the schema.

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 ('List') and resource ('users who have a given realm role'), plus the clarifying question 'who has this role?' This clearly conveys the tool's purpose and differentiates it from sibling tools like get_group_members or get_user_role_mappings.

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?

Usage is implied through the 'who has this role?' phrasing, but there is no explicit guidance on when to choose this tool over alternatives such as keycloak_get_group_members or keycloak_get_user_role_mappings. No exclusions or alternative tool names are mentioned.

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

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

The annotations already declare readOnlyHint=true, covering the read-only safety profile. The description adds the aggregation scope (per client, across realm), but does not clarify details like whether offline sessions are excluded, pagination behavior, or the exact structure of the returned data.

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, front-loaded sentence with no filler. The key scope ('per client across the realm') appears early and the phrasing is efficient.

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 simple read-only count tool with one optional parameter and no output schema, the description supplies sufficient scope and intent. It could be more precise about what 'active sessions' includes and what the response contains, but the core information needed to select and invoke the tool is present.

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% for the single optional 'realm' parameter, including its default value. The description adds no parameter-specific information, but the schema already fully documents the parameter.

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 the specific verb 'count' and clearly identifies the resource: active sessions per client across the realm. This distinguishes it from sibling tools like keycloak_get_client_sessions or keycloak_get_client_session_count, which focus on a single client.

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 implies when to use the tool: when a realm-wide per-client session count is needed. However, it does not explicitly state when not to use it or name alternative tools, leaving some routing to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds behavioral value by warning that roleId must be the UUID, not the name, and by pointing to the source tool for that UUID. It does not mention recursion or pagination, but for a simple read-only list this is acceptable.

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, no filler. The primary action is stated first; the important identification caveat is front-loaded next. Every sentence 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?

For a simple read-only operation, the description covers the core usage and the key input pitfall. No output schema exists, but the action implies the return is the list of contained roles. It could optionally clarify whether nested composites are expanded, but that is not required for correct basic invocation.

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 coverage is 100% and already describes roleId as 'Role UUID, from the `id` field of a role.' The description adds the explicit negative constraint 'not its name' and the cross-reference for obtaining the correct value, which is meaningful disambiguation beyond the schema.

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?

States a specific action ('List the roles contained in a composite role') on a clear resource. The immediate caveat about using UUID rather than name further distinguishes it from role-lookup siblings like keycloak_get_realm_role.

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 clear context: use this when you have a composite role and want its contained roles. It also supplies a cross-reference to keycloak_get_realm_role to obtain the needed UUID, which is a practical prerequisite. It does not explicitly list when not to use it or compare with alternatives, but the intended use is evident.

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

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

With readOnlyHint=true already declaring the safety profile, the description adds real behavioral value beyond the annotation: it warns that the raw endpoint dumps every SPI provider and theme, quantifies the size (~1MB), and explicitly states this tool returns only the useful head. This manages agent expectations about response size and omitted content. No contradiction with the readOnly annotation.

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 with zero waste. The primary content categories are front-loaded in the first sentence, and the second sentence adds the truncation behavior with a concrete size estimate. Every clause earns its place, and nothing is repeated from the schema or annotations.

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 zero-parameter, read-only informational tool with no output schema, the description is largely sufficient: it enumerates the content areas and explicitly bounds the response by excluding the SPI/theme dump. The only gap is that it doesn't hint at the return structure (formatted summary vs. raw JSON fields), but for an agent deciding whether to call this tool to answer server-metadata questions, the practical information is present.

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 tool has zero parameters, so the baseline is 4 per the rubric — there is nothing for the description to add about parameter meaning. The description instead clarifies what data the no-arg call will yield (version, uptime, JVM/memory, feature flags), which is the relevant semantic information for an empty-schema tool.

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 enumerates what the tool returns — server version, uptime, JVM/memory info, and enabled feature flags — which identifies it as a server-level metadata read. It is implicitly distinguished from all 45 sibling tools, none of which target server info, and the second sentence further separates it from the raw endpoint. A minor gap: the verb 'returns' appears only in the second sentence rather than front-loaded, and the resource is implied rather than explicitly stated.

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?

Usage context is implied: the description signals this is the trimmed, useful-head variant of a much larger raw dump (~1MB), so an agent understands this tool is the compact choice. However, it never explicitly states when to use this tool versus alternatives, and among siblings the generic keycloak_request passthrough is a plausible alternative that is never mentioned. The guidance is inferable but not stated.

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

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.

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

The readOnlyHint annotation already establishes the safe read-only behavior. The description adds scope context (groups belonging to a user) but does not disclose extra behavioral traits such as return shape, pagination behavior, or whether only direct memberships are returned. With annotations covering the safety profile, this is adequate but not rich.

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?

A single, front-loaded sentence with zero waste. It conveys the essential purpose without redundancy.

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 simple read-only list operation, the description combined with the fully documented schema is sufficient for an agent to select and invoke the tool. The only minor gap is that no output schema or return-format note is provided, but the name and description make the result type inferable.

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 all four parameters (userId, max, first, realm) described in the schema. The tool description itself adds no parameter-level meaning, so the baseline of 3 applies.

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 'List the groups a user belongs to' uses a specific verb and resource with a clear scope (a user's groups). It is clearly distinguishable from siblings like keycloak_list_groups (all groups) and keycloak_get_group_members (users in a group).

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 clear context: this is the tool for retrieving groups for a specific user, implying when it should be selected over list_groups or get_group_members. It does not explicitly name alternatives or exclusions, but the scope is unambiguous.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds meaningful behavioral context beyond the annotation: default direct-only semantics, inclusion of inherited and composite roles when `effective` is set, and the consequence that this matches the token's role set. No contradictions.

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, no filler, and the most important behavioral distinction is front-loaded. Every clause contributes to correct usage.

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 simple read-only lookup with well-documented parameters and a readOnly annotation, the description is largely complete. The main gap is that no output schema exists and the response shape is not described, but the domain concept of role mappings makes the return type reasonably predictable.

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 coverage is 100% with strong descriptions for `realm`, `userId`, and `effective`. The free-text description adds value beyond the schema by explaining that `effective` produces the set that 'actually lands in their token,' which gives the agent a clearer reason to set the flag.

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 states a specific verb and resource: retrieving a user's role mappings. It further clarifies the direct vs. effective distinction, which sets it apart from siblings like keycloak_get_group_role_mappings and makes its scope immediately clear.

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 default behavior is explicit, and the description tells the agent when to set `effective` — when inherited roles and the actual token role set are wanted. It doesn't name sibling alternatives explicitly, but the direct/effective guidance is actionable and clear.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds meaningful behavior beyond it: only active sessions are listed, and the returned information includes location and timing. This helps set expectations for a read-only listing operation.

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 front-loaded sentence with no filler or redundant detail. The verb and resource appear immediately, and the parenthetical adds useful scoping without bloating the text.

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 simple read-only list operation, the description plus detailed schema is sufficient: required parameter is documented, optional realm is clarified, and the return scope is summarized. The main gap is the absence of usage routing relative to sibling session tools, but this does not prevent correct invocation.

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%, and the schema already explains the realm default and clarifies that userId is a UUID, not a username, with a pointer to keycloak_list_users. The tool description itself adds no parameter-level meaning beyond this, so baseline 3 is appropriate.

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 ('List') and a precise resource ('a user's active SSO sessions'), with the parenthetical clarifying the kind of information returned. This clearly differentiates it from sibling tools like keycloak_get_client_sessions and keycloak_get_realm_session_stats.

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 no explicit guidance on when to use this tool versus related session/realm tools, and it names no alternatives or exclusions. Usage context is only implied by the tool name and resource phrasing.

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

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

Annotations already declare readOnlyHint=true, lowering the burden. The description adds non-obvious behavioral context by noting that admin event logging must be enabled for the query to be meaningful, and frames the result as audit-trail data. It does not describe return shape or behavior when logging is disabled, but the prerequisite is a valuable disclosure.

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 one tight sentence that leads with the core action, defines the resource, gives concrete examples, and adds a necessary prerequisite. Every clause earns its place; there is no filler.

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 read-only list/search tool with a rich schema covering most of the 10 parameters, this description is largely sufficient. It provides the domain framing and prerequisite, while the schema handles filters and paging. It could be more complete about return value assumptions and ordering, but no output schema exists and the described scope is clear.

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 90%, so the schema already documents most parameters. The description's examples ('who created this user, who changed that client') loosely map to authUser/authClient filters but add no direct parameter-level details beyond what the schema provides. Baseline 3 is appropriate.

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 ('Search') with a specific resource ('admin events') and defines what those are: the audit trail of realm changes. It provides concrete examples and conceptually distinguishes this from keycloak_list_events, which covers user events.

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 clear context for when to use this tool: for changes made to the realm itself, not user-level activity. It also includes a prerequisite ('Requires admin event logging to be enabled'). It does not explicitly name alternatives or conditions under which another tool should be used, so it stops short of a 5.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation, so the description does not need to restate that. It adds useful conceptual context about what authentication flows are, but does not disclose behavior such as response shape, ordering, or whether only top-level flows are returned.

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, well-structured sentence that leads with the action and resource, then uses an em-dash to add clarifying detail. Every part is informative and there is no wasted wording.

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 simple read-only listing operation with one optional parameter, the description covers the essential purpose and gives helpful examples of flow types. The lack of an output schema is mitigated by the straightforward nature of a list operation, though a brief note on returned fields would 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?

The only parameter, 'realm', is fully documented in the input schema with its default behavior. The description adds no additional parameter-level detail, which is acceptable because schema coverage is 100%.

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 ('List') and resource ('authentication flows'), and clarifies what those flows are with concrete examples (browser, direct grant, registration, reset credentials). This makes the tool's purpose distinct from related siblings like keycloak_get_authentication_flow_executions.

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 no guidance about when to use this tool versus related alternatives such as keycloak_get_authentication_flow_executions or keycloak_get_realm_flow_bindings. It states what the tool does, but not the conditions or context that should lead an agent to choose it.

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

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

Annotations already declare readOnlyHint=true, and the description is consistent with that. It adds valuable behavioral scope by clarifying that realm-management's roles are actually client roles, which corrects a likely incorrect expectation about what this endpoint returns. This goes beyond the annotation alone.

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 concise sentences with no filler. The core purpose is front-loaded, and the clarifying realm-vs-client-role note is placed immediately after. Every sentence 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?

For a read-only list tool, the description plus schema is nearly complete. It explains the key distinction from realm roles, the required clientUuid is documented, and pagination/offset defaults are in the schema. The lack of an output schema is not a major gap for a simple list operation, though a brief mention of return shape could be argued.

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 high (80%), so the schema already documents the main parameters well. The description does not add parameter-level meaning beyond what the schema provides. The clientUuid lookup semantics are already covered in the schema, so the description adds minimal parameter value. Baseline 3 is appropriate.

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 verb and resource: 'List the roles defined by a client.' It also distinguishes this from realm roles, which is essential because sibling tools include keycloak_list_realm_roles. The realm-management example reinforces the distinction and prevents a common misclassification.

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 implies when to use this tool versus keycloak_list_realm_roles by noting client roles are distinct from realm roles. It does not name the alternative explicitly or state exclusions, but the realm-management example provides clear contextual guidance about the boundary.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds useful behavioral context by stating what the response contains (`id` and `clientId`), which is valuable for downstream tool orchestration, though it does not disclose additional behaviors like pagination limits or authentication requirements—though those are partially covered by the schema.

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 two focused sentences with no wasted words. It front-loads the purpose and then adds a practical clarification about the two identifier fields, which is exactly the kind of information an agent needs.

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 schema fully documents all optional parameters, and the description adds the important `id` vs `clientId` distinction needed for chaining into other client tools. Despite having no output schema, the description adequately signals the return content. A small gap is the absence of explicit mention of pagination or result ordering, but the schema covers the pagination 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 100% for all 6 parameters, so the schema already documents each parameter's meaning. The description does not add additional parameter-level detail, so the baseline score of 3 applies.

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 opens with a specific verb and resource: "List the realm's clients (applications)." It clearly identifies what is returned and explains the distinction between `id` and `clientId`, which also helps differentiate this list operation from sibling tools like keycloak_get_client.

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 signals when to use this tool by noting that `id` is "the UUID every other client tool needs," making it the natural lookup step before calling related client tools. It does not explicitly name alternatives or say when not to use it, but the usage context is clear.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds useful domain context about client scopes. It does not add behavioral details such as pagination, ordering, filtering, or return shape, but none are required for a simple read-only list given the annotation.

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 with no wasted words: the first states the action, the second explains the domain concept. The key action is front-loaded and easy to parse.

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 read-only, one-parameter list operation, the description is sufficiently complete. It lacks explicit notes on return values or pagination, and does not route to sibling tools, but the annotation and simple schema cover the main safety and parameter concerns.

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 schema documents the only parameter (realm) with 100% coverage, including its default behavior. The description adds no parameter-specific meaning beyond what the schema already provides, so baseline 3 is appropriate.

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 and resource: 'List the realm's client scopes.' This clearly distinguishes it from single-scope retrieval or scope evaluation siblings, though it does not explicitly name those alternatives.

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?

There is no guidance about when to use this tool versus keycloak_get_client_scope, keycloak_get_client_assigned_scopes, or keycloak_evaluate_client_scopes. The conceptual explanation implies relevance to token claims but does not state a selection rule.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds the useful prerequisite that event logging must be enabled on the realm, but it doesn't disclose other behavioral aspects such as result ordering, pagination behavior, or that only currently retained events are searchable.

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 with zero filler. The core action is front-loaded, the use case is immediately actionable, and the prerequisite is stated compactly. 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?

For a search tool with 9 optional parameters, read-only annotations, and no output schema, the description covers the essential context: what it searches, why you'd use it, and an important prerequisite. It doesn't describe the return shape, but that is often unnecessary for a list/search tool when parameters are well-documented in the schema.

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 89%, so the input schema already documents all but the ipAddress parameter. The description's event type examples mirror the 'type' parameter but add minimal new meaning. This is the baseline 3 for high schema coverage where the schema carries the semantic burden.

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 states a specific verb and resource ('Search user events') and lists concrete examples (logins, logouts, failed logins, registrations) that make the tool's function immediately obvious. It also differentiates from the sibling keycloak_list_admin_events by explicitly scoping to user events, even though it doesn't name the sibling.

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 use case ('why can't this user log in?') and a prerequisite ('Requires user event logging to be enabled on the realm'), providing actionable context for when to use it. It doesn't explicitly exclude alternatives like keycloak_list_admin_events, but the focus on user events makes the intended scope evident.

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

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

The readOnlyHint annotation already covers the safety profile, so the description's burden is reduced. It adds real behavioral value beyond the annotation by disclosing that groups form a tree and that the response nests subGroups inside top-level groups — important for an agent expecting a flat array. It does not contradict the annotation and provides the key response-shape insight an agent needs.

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 totaling roughly 25 words with zero filler. The purpose is front-loaded, and the tree/nesting disclosure earns its place because it shapes the agent's expectation of the response structure. Nothing extraneous could be removed without losing information.

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 tool with 7 optional parameters and no output schema, the description covers the most critical return-value behavior (tree nesting) while the rich schema documents parameter semantics. The readOnlyHint annotation completes the safety picture. A minor gap is that pagination's interaction with the nested tree structure is never clarified, but this is a subtle edge rather than a blocking omission.

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 86% (6 of 7 parameters documented), which exceeds the 80% threshold, so the baseline of 3 applies. The description itself adds little parameter-level meaning; its tree-nesting note is about output shape, only marginally relevant to briefRepresentation. The schema's parameter descriptions (e.g., q's attribute-search syntax, max bounds, pagination offset) carry the heavy lifting, so no penalty but also no bonus.

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 ('List') and resource ('the realm's groups'), making the core purpose unambiguous. It adds a genuinely distinguishing structural detail — top-level groups come back with subGroups nested inside — which clarifies what the agent will receive. However, it does not explicitly contrast with siblings like get_group, get_user_groups, or get_group_members, so it stops short of full sibling differentiation.

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 purpose statement 'List the realm's groups' implies the usage context: call this when you need the full realm group hierarchy rather than a user's groups or a group's members. But there is no explicit when-not guidance or naming of alternatives, despite 46 siblings including several overlapping group tools. The guidance is implied, not stated.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds meaningful context by explaining the nature of the mappers and their role in claim translation. There is no contradiction, and the additional context avoids ambiguity without overpromising behavior.

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?

A single sentence carries the entire definition with no wasted words. The primary action and resource are front-loaded, and the clarifying clause adds the core concept without bloating the description.

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 simple read-only listing tool with only two parameters and complete schema coverage, the description is nearly sufficient. It could be slightly stronger by explicitly contrasting with the client-side protocol mapper listing tool, but nothing essential for invoking the tool correctly is missing.

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 schema already covers both parameters thoroughly, including the alias semantics and the realm default. The description reinforces that aliases refer to identity providers but adds no new parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.

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 ('List') and a precise resource ('an identity provider's mappers'), then defines what mappers are: rules translating claims from external IdPs into Keycloak users, roles, and groups. This clearly differentiates the tool from similar listing tools like keycloak_list_protocol_mappers.

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 implies the tool should be used when the agent needs to see identity-provider-level claim translation rules. It does not explicitly name alternatives such as keycloak_list_protocol_mappers or state when not to use this tool, so the guidance is useful but not fully explicit.

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

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

With readOnlyHint=true already covering the safe read-only nature, the description adds value by warning that client secrets are redacted in the results, which is a non-obvious behavioral trait. It also provides useful domain context that identity providers are external login sources. This exceeds the baseline set by the annotations without contradicting them.

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, front-loaded sentence that immediately states the action and resource, then provides parenthetical examples and a useful redaction note. Every element earns its place and there is no redundant filler.

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 simple read-only listing tool with one optional parameter, the description covers the purpose, the domain concept, and an important output detail about redacted secrets. It does not explicitly mention the return shape, but that is largely inferable for a list operation. A brief pointer to the singular get_identity_provider tool would 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?

The sole parameter 'realm' is fully documented in the input schema, including its default behavior via KEYCLOAK_REALM, so schema description coverage is 100%. The description text itself adds no extra parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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 opens with a specific verb and resource, 'List the realm's identity providers', and clarifies what identity providers are with concrete examples like Google, GitHub, SAML, and OIDC IdP. The plural 'List' clearly distinguishes this from the sibling keycloak_get_identity_provider without requiring the agent to open 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 clearly implies that this tool is for enumerating all identity providers in the realm. However, it does not explicitly state when to prefer keycloak_get_identity_provider for a single provider or keycloak_list_identity_provider_mappers for mappers. The context is clear, but exclusions and alternatives are left implicit.

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

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

The readOnlyHint annotation already signals that this is a safe read-only operation. The description adds useful conceptual context about what a protocol mapper is, but does not disclose additional behavioral aspects such as return format or pagination. With annotation coverage, this sits at a solid baseline.

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 with no filler; the first sentence states the operation and target, and the second briefly explains why mappers matter. The definition is front-loaded and every sentence 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?

For a simple read-only list tool with fully documented parameters and a readOnlyHint annotation, the description is complete enough for an agent to select and invoke the tool. The target (client or client scope), the purpose, and the relevant parameter relationships are all represented either in the description or the input schema. The absence of an output schema is not critical because the result is naturally the list of mappers.

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?

All three parameters have schema descriptions, including the OR relationship between scopId and clientUuid, so the schema carries the operational meaning. The description's 'client or client scope' phrase roughly mirrors those parameters but adds no new detail about realm defaults, UUID formats, or mutual exclusivity beyond what the schema already states.

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 resource pairs: 'List the protocol mappers on a client or on a client scope.' It states exactly what the tool returns and explains the domain concept (mappers add claims to a token), which makes the purpose unambiguous. The word 'protocol' also distinguishes it from the sibling keycloak_list_identity_provider_mappers.

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 usage context is implied by describing the resource and target ('on a client or on a client scope'), but there is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as identity provider mappers. An agent can infer when to call it, but the definition does not explicitly route the decision.

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

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

The readOnlyHint annotation already establishes the non-destructive read profile, so the description does not need to restate that. It adds the realm-level scope but does not disclose additional behaviors such as pagination behavior or the large-response risk; the latter appears only in the briefRepresentation parameter description.

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 one short sentence with no filler or redundancy, and the key action and resource are front-loaded. 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?

The description is sufficient for a basic read-only list operation when combined with the parameter schema and readOnlyHint, but it leaves no room for disambiguation among many sibling role/group/user list tools and does not describe the return shape (no output schema is present).

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%, so the baseline is 3 even though the tool description adds no parameter detail. However, the schema's 'search' parameter description is mis-copied from 'realm', and the tool description does not compensate for that potential confusion.

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 states a specific verb ('List') and a precise resource ('realm-level roles defined in a realm'), which distinguishes it from related siblings such as keycloak_list_client_roles and keycloak_get_realm_role. It is not a tautology and adds useful realm-vs-client scope.

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?

There is no guidance on when to use this tool versus alternatives, no mention of sibling tools, and no exclusion criteria. The description only states what the tool does; an agent must infer selection from the tool name and the sibling list.

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

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

Annotations already declare readOnlyHint=true, and the description consistently treats this as a read operation. It adds the behavioral nuance that results are scoped to the token's visibility, but it does not disclose return format, pagination, ordering, or potential size aside from what the parameter schema already warns about. This is adequate but not rich behavioral disclosure.

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 tight, front-loaded sentence with no filler; every word adds meaning. The parameter description in the schema is equally economical while conveying the key operational caution.

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 simple read-only list tool with one optional, fully documented parameter, the definition gives enough to call it correctly and to avoid flooding context by keeping briefRepresentation=true. A brief note on pagination or explicit return type would fully close the gap, but nothing essential is missing for basic invocation.

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%: the single parameter briefRepresentation is fully documented with a default value and a clear usage warning about context flooding. The tool description itself adds no parameter-level meaning, so it stays at the expected baseline for high-coverage schemas.

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?

Clearly states the action (List) and resource (realms), and adds a valuable scoping qualifier ('this token can see') that distinguishes it from singular-fetch tools like keycloak_get_realm. The verb+resource pair is unambiguous even within a large sibling set.

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 implies enumeration of token-accessible realms and gives a useful context cue about authorization scope, but it does not explicitly state when to prefer this over alternatives like keycloak_get_realm or when not to use it. Exclusions and alternative routing are left to inference from the tool names.

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

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

The annotations already declare readOnlyHint=true, so the description only needs to add behavioral context beyond that. It does clarify the returned information includes enabled/default flags, which is useful. However, it doesn't mention pagination, realm defaulting behavior, or other response characteristics, so the added transparency is modest.

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 that front-loads the action and resource, then gives the key output detail. No filler or redundant phrasing.

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 simple read-only list operation with one optional, well-documented parameter, the description is complete. It states what the tool lists and what information is returned, and the schema covers the only parameter. No output schema exists, so the description appropriately exposes the return semantics.

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 only parameter, realm, is fully described in the schema (100% coverage), including its default behavior. The description does not add new parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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 ('List') and resource ('the realm's required actions'), and adds concrete detail about what is reported: whether each action is enabled or applied to new users by default. This clearly distinguishes it from the sibling list tools, none of which target required actions.

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 tool's purpose is immediately clear from the description: query the realm's required actions and their default/enabled state. It doesn't explicitly contrast with alternatives or state when not to use it, but for a simple read-only list tool this context is sufficient.

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

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.

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

The annotations already mark the tool as read-only, but the description adds valuable behavioral detail: only GET is permitted, writes are disabled, and enabling mutations requires KEYCLOAK_ALLOW_WRITES=1. It also explains how paths are resolved relative to the realm or as absolute /admin paths, which is not inferable from annotations.

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?

Four sentences with no filler. The opening label 'Escape hatch' immediately conveys purpose, and the path rules, method restriction, and env-var override are each expressed in one compact clause.

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 generic raw-endpoint tool with arbitrary output, the description supplies the critical decision rule, path semantics, and method constraint. The remaining body/query/realm details are adequately documented in the input schema, and no output schema means there is no promised return-shape to disclose.

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 schema already covers most parameters (80% coverage), and the description adds crucial path-construction semantics: realm-relative vs absolute /admin paths. It does not explain body or query serialization beyond the schema, but the high schema coverage makes that acceptable.

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 this is an escape hatch for calling any Keycloak Admin REST endpoint directly, and it names concrete use cases that the curated siblings do not cover (user federation components, authorization policies, organizations, partial import/export, credentials). It distinguishes itself from the large sibling list by emphasizing 'when no curated tool fits.'

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?

It explicitly instructs the agent to use this tool when no curated tool fits, and gives concrete examples of such cases. It also specifies the current write limitation, so an agent will not try to use it for mutations unless the environment variable override is present.

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

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

Beyond the readOnlyHint annotation, the description explains a non-obvious behavioral nuance: roles are read from server-side account role mappings rather than from the token, and tokens may contain no role claims for some clients. This is valuable context that prevents an agent from misinterpreting token contents as authoritative.

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 compact and information-dense, with no filler. Every sentence earns its place: the first defines what is shown, the second adds a critical caveat about role source, and the third gives a direct call-to-action. The most actionable instruction appears last but is short and memorable.

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 parameterless read-only diagnostic tool, the description covers output content, data origin, a caveat about token semantics, and a concrete trigger for use. Nothing an agent needs to decide when and why to call this tool is missing, and no output schema exists that would need to be summarized.

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 tool has zero parameters and the schema coverage is trivially 100%, so the description is not required to document parameter semantics. The baseline of 4 applies because there are no parameters to explain and the description does not need to compensate for any schema gaps.

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 states a precise purpose: show who the server is authenticated as and what it is allowed to do, listing concrete fields such as issuing realm, client, acting user, token expiry, and realm-management roles. This clearly distinguishes it from the broader sibling tools by focusing on identity and authorization context for the server's current credentials.

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, actionable usage directive: 'Call this FIRST when another tool returns 403.' It does not enumerate exclusions or explicitly compare against keycloak_auth_status, but the scenario-based guidance is specific enough to tell an agent when to invoke this tool over others.

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