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

Annotations already declare read-only, non-destructive, idempotent. Description adds return format details (JSON array with specific fields) and confirms no data modification, complementing 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?

Two sentences, no wasted words. Front-loaded with purpose, then provides detail and use case. Every sentence is informative.

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 parameters, annotations cover safety, and no output schema, the description fully explains what the tool does and returns. No missing information.

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?

No parameters exist (100% schema coverage). Description adds value by explaining the output structure (JSON array with alias, description, etc.), which is beyond the empty 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 clearly states it lists all authentication flows in the configured realm, using specific verb 'lists' and resource 'authentication flows'. It distinguishes from siblings like keycloak_auth_required_actions_list which list different resources.

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?

Explicitly mentions using it to inspect/audit flows before configuring related settings, providing clear context. Does not explicitly state when not to use, but the purpose is well-defined.

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?

Describes write operation as non-destructive and idempotent, aligning with annotations and adding context that setting already-matching state leaves action unchanged.

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?

Three concise sentences: purpose, behavioral traits, usage guidance and return info. No unnecessary words, all earn their 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?

Covers prerequisite (list tool), idempotency, return type (short text confirmation). No output schema needed as description explains return value.

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?

Adds meaning beyond schema: explains alias format with examples, and clarifies idempotency of the enabled parameter. Schema coverage is 100% but description enriches 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?

Clearly states the verb (enable/disable), resource (required action), and context (Keycloak realm by alias). Differentiates from sibling tools by specificity.

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?

Explicitly advises calling keycloak_auth_required_actions_list first to obtain valid aliases. Does not mention when not to use, but the guidance 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?

Annotations already provide readOnlyHint, destructiveHint, idempotentHint. Description adds return format details (JSON array with fields alias, name, enabled, defaultAction, priority) and confirms no data change, providing context beyond 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?

Three sentences: first states purpose, second adds read-only and return details, third provides usage guidance. Efficient, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, description comprehensively explains return format. Context (Keycloak realm, currently configured) is clear. Low-complexity tool fully described.

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 has no parameters (100% coverage), baseline 4. Description does not need to add parameter info; it correctly omits irrelevant parameter details.

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?

Description explicitly states it lists required actions, provides examples (Verify Email, etc.), and distinguishes from sibling tool keycloak_auth_required_action_set_enabled by noting its use for discovering aliases.

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?

Clearly states it is read-only, idempotent, takes no parameters, and explicitly recommends using it before enabling/disabling a required action with keycloak_auth_required_action_set_enabled, providing when and alternatives.

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?

Discloses read-only, idempotent nature (no writes, same data for unchanged config) and explains possible return values (JSON array or 'Client not found'), adding context beyond 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?

Two sentences that efficiently convey purpose, behavior, usage, and output with no redundant 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?

Given no output schema, the description fully explains the return type (JSON array) and error case, making it complete for a simple read-only 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?

The schema description covers the parameter fully (100% coverage), but the description adds extra context: clarifies the id is UUID-style, not human-readable, and how to obtain it. This justifies a score above 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 clearly states the tool lists authorization-services permissions on a Keycloak client, defines what permissions are, and distinguishes from sibling tools like keycloak_authz_resources_list and keycloak_authz_policies_list by suggesting pairing.

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?

Explicitly states when to use (to see how a client's resources are protected), prerequisites (call keycloak_clients_list first to get the internal id), and pairs with other tools for full context.

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?

Adds behavioral context beyond annotations: explicitly states read-only and idempotent nature, and mentions possible 'Client not found' return. Annotations already cover safety profile, so description adds value without 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?

Concise single paragraph of four sentences, each serving a purpose: purpose, behavior, usage guidance, return format. 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?

Sufficiently complete given tool simplicity: describes return value (JSON array or error text), provides context for integration with sibling tools, and no output schema is needed because description covers it.

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?

Adds significant meaning beyond schema: clarifies that clientId is the UUID-style internal id (not the human-readable name) and directs to obtain it from keycloak_clients_list. Schema coverage is 100%, but description enhances understanding.

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 it lists authorization policies on a Keycloak client, specifying the resource and scope. Distinct from sibling tools like keycloak_authz_resources_list and keycloak_authz_permissions_list by focusing on policies.

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?

Provides explicit guidance to first call keycloak_clients_list to get the client's internal id, and suggests combining with related authz tools. Lacks explicit when-not-to-use but 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?

Description adds behavioral details beyond annotations: stating read-only, idempotent, return format (JSON array or error text), consistent with annotations and 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?

Description is concise, well-structured, front-loads core action, followed by behavior, usage instructions, and return info. No extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description fully explains return format and error case. It also provides context on prerequisites and sibling tool relationships, making it complete for the tool's simplicity.

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?

Input schema already provides a thorough description for clientId (internal UUID, how to obtain). The description reinforces this but does not add new semantic meaning beyond schema coverage, keeping baseline at 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists authorization resources on a Keycloak client and distinguishes it from sibling tools for policies and permissions by specifying 'protected resources that policies and permissions apply to'.

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?

Explicitly advises to call keycloak_clients_list first for the client internal id, and to pair with keycloak_authz_policies_list and keycloak_authz_permissions_list for a full picture, providing clear when-to-use and combinatorial 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?

Annotations already indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds value by explicitly stating it is a write operation, not idempotent, and will cause a conflict on duplicate rather than updating. It also mentions the return value (confirmation message). 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?

Three concise sentences with no wasted words. The first sentence clearly states the tool's purpose, the second explains non-idempotency, and the third provides usage alternatives. Front-loaded and 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?

Given the full schema coverage, clear annotations, and no output schema, the description covers all necessary behavioral context: creation, non-idempotency, conflict behavior, return value, and relationship to sibling tools. No gaps identified.

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 description does not add new meaning beyond what is already in the input schema. It does not repeat parameter details but also does not compensate for any gaps, 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 clearly states it creates a new OAuth/OIDC client in the configured realm. It uses a specific verb ('create') and resource ('client'), and differentiates from sibling tools like keycloak_client_list and keycloak_client_update by mentioning their respective roles.

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?

Explicitly advises to verify clientId uniqueness using keycloak_client_list or keycloak_client_get before creation, and to use keycloak_client_update for modifications. Also notes the operation is not idempotent and will cause a conflict on duplicate, providing clear when-to-use and when-not-to-use 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?

Annotations already declare the tool as read-only, non-destructive, and idempotent. The description reinforces this ('read-only, idempotent operation') and adds specifics about return format and error case, providing useful behavioral context beyond 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?

Three sentences, each purposeful: first states purpose, second gives usage guidance, third explains return format. No redundant information; well-structured and 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 the tool's simplicity (one parameter, no nested objects), the description fully covers behavior, parameter semantics, and return value (including error case). No output schema needed; description alone is 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 covers the clientId parameter with 100% description. The description adds critical distinction that it is the internal UUID (not human-readable clientId) and provides an example, enhancing usability over schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Lists the default client scopes') and the resource ('a single client'), distinguishing it from sibling tools like keycloak_client_scopes_list which lists all available 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?

Explicitly advises when to use this tool ('before assigning or unassigning one') and directs to an alternative (keycloak_client_scopes_list) for the full catalog, providing clear context for selection.

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 indicate destructiveHint=true and idempotentHint=false. The description adds important behavioral details: non-idempotent nature, need for explicit confirm=true, and return values (confirmation message or reason string). No contradictions with 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 two concise sentences. The first sentence states the purpose and permanent nature; the second adds behavioral details and comparisons. No fluff, 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?

Given the absence of an output schema, the description mentions return values (confirmation message or reason). It covers prerequisites (verify with get), safety (confirm parameter), and idempotency. Completely sufficient for an agent to use 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 coverage is 100% with descriptions for both parameters. The description adds clarity: clientId is the human-readable OAuth/OIDC identifier (not UUID), confirm must be true to actually delete, and explains the guard behavior. This enhances understanding beyond 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 clearly states the tool's purpose: 'Permanently delete a client from the realm.' It specifies the verb (delete), resource (client), and permanence. The sibling tools include update and get, so it distinguishes itself effectively.

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 explicitly advises when to use alternatives: 'Use keycloak_client_get to verify the target first, and keycloak_client_update to merely disable a client instead of removing it.' It also explains the confirm parameter's role in preventing accidental deletion, providing clear usage context.

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?

Even with annotations providing readOnlyHint, destructiveHint, idempotentHint, the description adds valuable behavioral context: it does not modify anything, returns a JSON object with specific fields, and handles 'Client not found' case. No contradiction with 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?

Two sentences with no unnecessary words. First sentence states purpose, second provides guidance and return info. Front-loaded and 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 tool with one required param, no output schema, annotations cover safety, the description explains the return value (fields and error message) completely. No missing context.

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?

Single parameter clientId is fully described in schema (coverage 100%). Description repeats that it's by clientId not internal UUID, which aligns with schema but adds no new semantics. 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?

Description clearly states 'Fetch a single realm client by its clientId' with specific verb and resource. Distinguishes from sibling keycloak_client_list by advising to use it first if clientId unknown.

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?

Explicitly says when to use (when clientId is known) and when to use alternative (keycloak_client_list for unknown clientId). Also notes read-only and idempotent nature, guiding safe usage.

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 read-only and idempotent; description adds that secret is masked by default and returns plaintext only with reveal=true. Notes return value format and error case for missing client.

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, front-loaded with main purpose. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 params and no output schema, description adequately explains behavior, return values, and error case. Sibling tools are listed but no further context needed.

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 covers both parameters fully (100%). Description adds context: clientId vs UUID, confidentiality requirement, and reveal parameter effect.

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?

Clear verb 'Read' and specific resource 'current secret of a confidential realm client'. Differentiates from sibling tools like keycloak_client_get (client info) and keycloak_client_regenerate_secret (rotation).

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?

Explicitly instructs to use keycloak_client_get first to confirm confidentiality, and mentions keycloak_client_regenerate_secret for rotation. Also advises on when to set reveal=true.

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, destructiveHint, and idempotentHint. The description adds the same info ('Read-only and idempotent; it does not modify anything') and clarifies return format. No contradiction, but minimal added value beyond 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?

Three sentences, front-loaded with the core purpose. Every sentence adds value: purpose, behavior, usage guidance, and return format. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description fully explains the return format (JSON array with specific fields). Combined with usage guidance and safety assurances, the definition is complete for a parameterless list 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?

No parameters exist, and schema coverage is 100%. The description explicitly states 'Takes no parameters', so the agent knows there are no inputs to configure. Baseline 4 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 ('OAuth/OIDC clients') with clear scope ('all...in the configured Keycloak realm'). It distinguishes from sibling tools like keycloak_client_get which retrieves 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?

Explicitly states when to use ('Use this to discover clients before calling keycloak_client_get, keycloak_client_update, or keycloak_client_delete') and mentions alternatives by name. Also notes it takes no parameters.

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, destructiveHint, idempotentHint. Description adds that it does not modify Keycloak, aggregates mappers, and returns 'Client not found.' when no match, providing behavioral context beyond 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?

Description is concise (4 sentences) and front-loaded with the main action. Well-structured with clear purpose, usage hint, and return value note. Slightly more verbose than necessary but no wasted sentences.

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?

No output schema, but description specifies return format (JSON array or 'Client not found.' text) and explains aggregation across client and scopes. Provides sufficient context for an agent to understand behavior and error cases.

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 has 100% coverage for the single parameter (clientId), already explaining it's an internal UUID and required. Description does not add extra parameter details; 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?

Description clearly states the tool lists protocol mappers for a single client, aggregated across client and scopes. Verb 'lists' and resource 'protocol mappers' are specific, and it distinguishes from sibling tools like keycloak_client_default_scopes_get.

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?

Provides guidance on when to use (inspect token shaping), and suggests an alternative sibling (keycloak_client_default_scopes_get) for finding scopes. Does not explicitly state when not to use, but 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?

Beyond annotations (destructiveHint=true, idempotentHint=false), the description adds critical behavioral details: the write is non-idempotent, invalidates the previous secret immediately, and requires confirmation. No contradiction with 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 concise (two sentences in a short paragraph) with no redundancy. It front-loads the action, then covers consequences, alternatives, and return value efficiently. 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?

Despite no output schema, the description clarifies the return value (new plaintext secret or reason string). It fully covers purpose, usage, behavior, parameters, and consequences. No gaps remain for an agent to select and invoke 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 coverage is 100%, but the description adds significant value: for clientId, it clarifies it's the human-readable identifier (not UUID) and the confidentiality requirement; for confirm, it explains the safeguard role and default behavior. This goes well 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 clearly states 'Regenerate (rotate) a confidential client's secret,' using a specific verb and resource. It distinguishes from sibling tools like keycloak_client_get_secret (read-only) and keycloak_client_update (non-secret updates).

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?

Explicitly mentions the alternative keycloak_client_get_secret for reading without rotating. Specifies the safeguard mechanism (confirm=true) and the consequence of invalidating the old secret. Provides clear when-to-use and when-not-to-use 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?

Reinforces read-only behavior (consistent with annotations), describes output as JSON array with fields, and mentions error message 'Client not found.' Adds context beyond 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?

Two sentences, no fluff, front-loaded with key info. Efficient and scannable.

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?

Fully covers input, output, error, usage guidance, and alternative. No missing pieces given low complexity and good annotations.

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 description does not repeat param details, but it adds value by clarifying clientId is UUID not human-readable name. Baseline 3, extra clarification bumps to 4.

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 tool lists client-level roles for a single Keycloak client, distinguishes from realm roles, and specifies read-only. Includes return format and error case.

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?

Explicitly tells when to use (discover roles before assignment) and when not (use keycloak_role_list for realm roles). Names sibling tool keycloak_user_client_role_assign.

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 description discloses that this is a write operation with idempotent behavior, aligning with the 'idempotentHint' annotation. It also details the return format: a confirmation message or a 'Not assigned:' message with reason. No contradictions with 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?

Three concise sentences: first states purpose, second adds behavioral traits (idempotent, return type), third gives usage guidance. Every sentence adds value, no 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?

The description fully covers the tool's behavior, prerequisites, and edge cases (non-existent client/scope). It references sibling tools for preparatory steps, making it self-contained for AI decision-making.

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?

With 100% schema coverage, the description adds crucial context: clarifies that clientId is the internal UUID (not the human-readable clientId) and provides examples for scope ('profile', 'email'). This reduces ambiguity 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 specifies the verb 'assign' and the resource 'existing realm client scope to a client as a default scope'. It clearly distinguishes itself from sibling tools like keycloak_client_default_scopes_get (which checks assignments) and keycloak_client_scopes_list (which lists available 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 description provides explicit guidance: 'Use keycloak_client_scopes_list to find a valid scope name and keycloak_client_default_scopes_get to check current assignments before calling this.' This tells the agent what to do before invoking the tool, including alternative tools for context.

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 readOnly, non-destructive, idempotent. Description adds return format (JSON array with id, name, protocol) and confirms no parameters, which is useful beyond 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?

Three sentences, front-loaded with purpose, then usage and return format. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only list tool, the description explains return value and usage. No output schema, but description compensates. 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?

No parameters exist, so schema coverage is 100%. Description doesn't add parameter-specific info, but none is needed. Baseline 4 for 0 params.

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 it lists every client scope in the realm (specific verb+resource). It differentiates from siblings like keycloak_client_scope_assign by indicating this is a discovery tool.

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?

Explicitly states to use it before assigning or unassigning scopes, providing clear when-to-use guidance. No alternatives are mentioned, but the 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?

Annotations indicate destructive and non-idempotent, but the description adds crucial detail: the confirmation gating, that subsequent calls after removal report 'Not removed', and the return message format. No contradiction with 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?

Description is a single paragraph of 5 sentences, packing necessary information without redundancy. It is efficient, though slightly verbose for a concise tool description. Could benefit from structured bullets but remains clear.

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?

Covers main action, prerequisite, behavioral details, and return messages. Lacks explicit error handling beyond return messages (e.g., client not found), but given the schema validation and the description, it is adequate for the tool's complexity.

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%, but the description enriches understanding by explaining the confirm parameter's default (false) and that scope should match a scope from the get tool. This adds value 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 clearly states 'Removes a default client scope from a client' with a specific verb and resource. It distinguishes from sibling tool keycloak_client_scope_assign (implicitly by mentioning the inverse operation) and provides context that it is destructive and requires confirmation.

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?

Explicitly advises using keycloak_client_default_scopes_get first to see current assignments. Also describes the behavior when confirm is false (does nothing) and the non-idempotent nature, providing clear guidance on tool usage.

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?

Discloses that it's a write operation and idempotent, matching the annotations. Adds that only supplied fields change and describes the return type (confirmation message or reason string). No contradiction with 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 concise sentences, each adding value: purpose, partial update, prerequisite advice, return info. No 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?

Covers purpose, behavior, prerequisites, and return type. Adequate for a tool with 5 parameters and no output schema, especially with good annotations.

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%, so baseline is 3. The description adds operational context but doesn't significantly enhance individual parameter meanings beyond the schema's own good descriptions.

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 'Update', the resource 'existing client', and the specific fields (enabled flag, public flag, redirect URIs, web origins). It distinguishes from sibling tools like keycloak_client_create and keycloak_client_get.

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?

Explicitly advises using keycloak_client_list or keycloak_client_get to find the client first, providing clear when-to-use guidance. Also explains partial update behavior.

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, destructiveHint, idempotentHint. Description restates read-only and idempotent, but adds context about the type of events (admin operations) and the response format (JSON array). 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, front-loaded with 'Read-only', no superfluous words. Every sentence adds value: first states purpose and read-only nature, second gives usage guidance and alternative.

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 parameter count, comprehensive annotations, and clear purpose differentiation from siblings, the description is complete. It explains what the tool does, its safety profile, when to use it, and the output 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?

Schema description coverage is 100% for the single max parameter. The description adds the default value (20) and clarifies it's an integer range, which goes beyond the schema's min/max constraints. However, it doesn't explain the effect of different values.

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 it returns admin events as JSON array, specific verb 'list' implied, and distinguishes from keycloak_events_login. The description includes example event types (CREATE, UPDATE, DELETE) which adds precision.

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?

Explicitly states when to use: for auditing admin changes. Directly contrasts with keycloak_events_login for end-user activity. Provides clear alternative, fulfilling the 'when not to use' 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?

Description states read-only, idempotent, and never modifies Keycloak, consistent with annotations. Adds ordering context.

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?

Three clear sentences, front-loaded with 'Read-only', no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers use cases, output format, ordering, and safety. No gaps given annotations and 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 coverage is 100%, description does not add meaning beyond schema. Baseline 3.

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 action (returns), resource (login events), and scope (realm's login event log). Differentiates from sibling keycloak_events_admin.

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?

Explicitly tells when to use (audit, investigate failed logins) and when not (use keycloak_events_admin for admin changes).

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, destructiveHint, idempotentHint. The description reinforces 'Read-only and idempotent; it does not modify any configuration.' and describes return values (JSON object or error text). 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 unnecessary words. First sentence states purpose, second provides usage and return behavior. Well-structured and 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 get-by-id tool with strong annotations, the description covers purpose, prerequisites, safety, and return behavior. No output schema, but description adequately explains return format. Complete and sufficient.

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 a detailed description for the 'id' parameter including an example UUID and instruction to obtain from list. The description adds value by connecting the parameter to the workflow and mentioning return format, but the schema already covers the parameter well.

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 'fetches' and specifies the resource 'user federation provider (such as LDAP or Kerberos)' and the method 'by its component id'. It clearly distinguishes from sibling tools like keycloak_federation_list and keycloak_federation_sync.

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?

Explicitly states the prerequisite: 'Use keycloak_federation_list first to obtain a valid id, then call this tool to inspect that specific provider.' Also describes what to do if id is invalid (returns 'not found'). Provides clear when-to-use 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?

Annotations already declare readOnlyHint, destructiveHint false, idempotentHint true. The description reinforces these by stating it is read-only and idempotent. It adds specific behavioral context: does not modify configuration, returns a JSON array with provider id, name, providerId. 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?

Three sentences, each earning its place: first states purpose and examples, second declares safety (read-only/idempotent), third provides usage guidance and output description. Front-loaded with key information. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately describes the return format (JSON array with id, name, providerId) and edge case (empty array). Covers all essential aspects: behavior, side effect, use case, output structure.

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 has 0 parameters with 100% coverage, so the description doesn't need to add parameter info. However, it adds value by describing the output structure and the purpose relative to other tools, which aids understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists user federation providers with specific examples (LDAP, Kerberos). It distinguishes itself from siblings like keycloak_federation_get and keycloak_federation_sync by indicating its role in discovery. The verb 'lists' and resource 'user federation providers' are precise.

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?

Explicitly advises users to use this tool to discover providers and obtain their ids before calling keycloak_federation_get for details or keycloak_federation_sync for sync. This provides clear when-to-use guidance and distinguishes from alternatives.

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?

Describes behavioral traits beyond annotations: clarifies it is a write operation, not destructive, not idempotent, and that each call re-runs the sync with potentially different import counts. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false).

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 concise sentences, each serving a purpose: purpose, behavioral traits, usage order, and return type. No redundant phrasing; front-loaded with the main action.

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 2 parameters and no output schema, the description covers essential context: purpose, use case, parameter details, and return value. Lacks some detail about error handling (e.g., if id is invalid), but is largely 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 coverage is 100%, but the description adds meaningful context: explains the id field as a Keycloak component UUID and where to obtain it, and describes the mode parameter's options and default behavior. This goes beyond the schema definitions.

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 'triggers a user synchronization' and identifies the resource as 'user federation provider' (e.g., LDAP). It explicitly distinguishes from sibling tools keycloak_federation_list and keycloak_federation_get by advising the agent to use them first to confirm the provider id.

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?

Provides explicit when-to-use guidance: use federation_list/get first to confirm provider id, then run this to refresh users. Also explains the mode parameter and its default behavior, and notes that the operation is not idempotent, which affects when to call 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 indicate non-readOnly, non-destructive, non-idempotent. The description adds that it is a write operation, confirms non-idempotency, and mentions the return value (confirmation message with group name). 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?

The description is three sentences, front-loaded with 'Write operation.' It is clear and efficient, though the first two sentences could be merged for even more conciseness.

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 tool with one parameter and no output schema, the description covers purpose, behavior, idempotency, and post-action. It could mention error conditions or auth requirements, but overall it is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds minimal value beyond the schema: it says 'top-level' and 'verbatim', but the schema already explains the parameter well. With 100% schema coverage, baseline is 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (create), the resource (top-level group), and the scope (realm). It distinguishes from sibling tools like keycloak_group_list and keycloak_group_delete by specifying 'top-level' and implying it's not for subgroups.

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 explicitly warns about non-idempotency and advises using keycloak_group_list afterward to get the group ID. It provides clear when-to-use context but does not explicitly mention when not to use it (e.g., if idempotency is needed).

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?

Adds significant context beyond annotations: irreversible deletion, includes membership/roles, return behavior. No contradiction with 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?

Three efficient sentences covering destructive nature, effects, prerequisite, and return behavior. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description mentions return message. All parameters explained. No missing context for a delete 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 coverage is 100%; description adds value by specifying that id must come from keycloak_group_list and that confirm gates deletion.

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 it deletes a group by ID, including membership and role assignments. Distinguishes from siblings like keycloak_group_list and keycloak_group_create.

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?

Explicitly instructs to find ID via keycloak_group_list first and explains the confirm parameter requirement. Does not state when not to use, but 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 description declares 'Read-only' and 'Idempotent', reinforcing annotations (readOnlyHint, idempotentHint). It also states the return format: a JSON array with id, name, path. 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?

Three sentences with no wasted words. Front-loaded with 'Read-only'. Every sentence adds 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 no parameters and no output schema but rich annotations, the description provides the return format and clear usage context. It is complete for this simple 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?

There are no parameters (0 params, 100% schema coverage). The description explicitly states 'takes no parameters', which is sufficient. Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists the realm's top-level groups (specific verb+resource). It distinguishes itself from sibling group write tools by positioning itself as a discovery tool.

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 explicitly says to use this to discover group IDs and names before calling group write tools, and names specific sibling tools like keycloak_group_member_add, keycloak_group_role_assign, keycloak_group_delete.

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?

Description states it is a write operation, idempotent (matching the idempotentHint annotation), and that it returns a fixed confirmation message. No contradictions with 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?

Three sentences, each serving a clear purpose: first identifies as write operation, second explains action and idempotency, third provides usage guidance. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description mentions the return behavior (fixed confirmation message). It covers behavioral traits, prerequisites, and idempotency, making it complete for the 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?

Schema coverage is 100% with descriptions for both parameters. The description adds extra context: IDs are UUIDs, examples given, and advises resolving IDs beforehand, which is 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 clearly states 'Adds an existing user to an existing group by their IDs.' This is a specific verb+resource combination that distinguishes it from sibling tools like keycloak_group_member_remove.

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?

Explicitly provides when-to-use guidance: 'Resolve the IDs first with keycloak_group_list and a user listing tool; to undo, use keycloak_group_member_remove.' This clearly indicates prerequisite steps and an alternative tool for the inverse operation.

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?

Discloses destructive nature, confirmation requirement, non-idempotency, and return message behavior beyond what annotations already provide. No contradiction with 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?

Three sentences, front-loaded with purpose and nature, followed by guidance and return info. No redundant or missing 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?

Comprehensive for a simple tool with 3 fully described parameters and no output schema. Includes prerequisites, behavior with confirmation, and return value.

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%; descriptions are clear. The tool description adds minimal extra parameter-specific value, only contextualizing the confirmation gate and ID resolution flow.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool removes a user from a group by IDs, distinguishing it from siblings like keycloak_group_member_add and keycloak_group_members_list.

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?

Explicitly provides prerequisites (resolve IDs with keycloak_group_list and keycloak_group_members_list first) and an alternative to reverse the operation (keycloak_group_member_add). Also notes it requires confirmation and is not idempotent.

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 description adds value beyond annotations by specifying the return format (JSON array of user objects with id, username, email (or null), and enabled status). Annotations already declare read-only and idempotent; the description confirms and elaborates.

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?

Three sentences, each serving a purpose: declaring idempotent/read-only, stating the function with prerequisite, and describing the return format. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with one parameter and no output schema, the description provides sufficient context: prerequisite, return format, and fields. It does not mention pagination or limits, but such details may be unnecessary for this 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 coverage is 100% with a detailed description for groupId. The description adds minimal extra meaning by reiterating that groupId is the UUID from keycloak_group_list, which is already implied in the schema. 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 'lists' and the resource 'users that are direct members of the given group.' It distinguishes from sibling tools like keycloak_group_list (list groups) and keycloak_user_groups_list (list user's groups) by specifying 'direct members.'

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?

Explicitly advises to resolve the group ID with keycloak_group_list first. While it does not provide when-not-to-use guidance, the context of sibling tools and the specific description make its usage clear for listing direct members only.

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?

Discloses idempotent behavior (matches annotation), write operation, and return value message including error reporting. The description adds context beyond the annotations, which already mark idempotentHint=true.

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?

Three sentences, each essential. Starts with operation type, then behavior, then prerequisites and return. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter idempotent assignment tool with no output schema, the description covers prerequisites, idempotency, return format, and error handling, making it fully self-contained.

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?

Adds critical context beyond schema: group ID should be resolved via keycloak_group_list, role name must match exactly. This aids correct parameter selection despite 100% schema 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 clearly states it grants a realm role to a group, making members inherit the role. It uses specific verbs ('Grants', 'assigns') and resource ('realm role', 'group'), distinguishing it from sibling tools like user_role_assign or client_role_assign.

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?

Provides explicit prerequisites: resolve group ID via keycloak_group_list and ensure realm role exists. Mentions idempotency. Does not explicitly state when not to use (e.g., for user roles), but sibling names imply the distinction.

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?

Describes non-idempotency, failure on duplicate alias, return value (confirmation message). Adds behavioral context beyond 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?

Three sentences, front-loaded with action, then behavioral detail, then workflow. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a create tool: covers pre-conditions, operation, post-verification, and return format. No output schema needed.

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 covers all parameters fully. Description reinforces alias as unique identifier and providerId as determining protocol, adding value beyond 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?

Clear verb 'Creates' and resource 'identity provider'. Distinguishes from sibling tools by referencing keycloak_idp_list and keycloak_idp_get for pre/post checks.

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?

Provides explicit guidance: check keycloak_idp_list first to avoid collisions, use keycloak_idp_get to verify. No explicit when-not-to-use, but 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?

Beyond annotations (destructiveHint=true, idempotentHint=false), description explains it is a permanent, destructive write, requires confirmation, and is not idempotent. It also describes the return message. No contradiction with 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?

Three sentences that are front-loaded with key information. No unnecessary words, each sentence adds 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?

For a simple two-parameter tool with no output schema, the description covers prerequisites, behavioral effects, and return value. It is fully complete given the context.

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%, but description adds meaning: alias is the unique alias as shown by keycloak_idp_list, and confirm must be true to proceed. Both parameters are well explained beyond 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?

Description clearly states the tool permanently deletes an identity provider by alias. It distinguishes from siblings like keycloak_idp_list and keycloak_idp_get by recommending their prior use to confirm the alias.

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?

Provides explicit when-to-use (delete an IdP) and recommends using list/get to confirm alias. The confirmation flag requirement is stated, but it does not explicitly mention 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, destructiveHint=false, and idempotentHint=true. The description reinforces these and adds context about the return value (JSON or 'not found'), enhancing transparency beyond 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 two concise sentences, front-loaded with the core purpose, and every sentence adds value 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?

Given the single parameter, presence of annotations, and no output schema, the description fully covers what the tool does, how to use it, and what to expect in return, making it complete for an AI 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?

Schema coverage is 100% with a description for the 'alias' parameter. The description adds value by referencing how to get the alias via keycloak_idp_list, providing practical usage guidance 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 clearly states it fetches a single identity provider by alias, using specific verbs and distinguishing from sibling tools like keycloak_idp_list which lists all providers.

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 explicitly suggests using it after finding the alias with keycloak_idp_list, providing clear usage context. While it doesn't state when not to use it, the guidance 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?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. The description adds that it makes no changes, takes no parameters, and returns a JSON array with specific fields. 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?

Three concise sentences: main action, safety note, usage guidance, and return description. No wasted words, front-loaded with purpose.

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 parameters and no output schema, the description fully covers what the tool does, its safety, when to use it, and what it returns. Complete for a simple list 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?

No parameters exist (0 params), so baseline is 4. The description adds value by describing the return structure (JSON array with alias, providerId, enabled, displayName).

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 'Lists all identity providers configured in the target realm.' It uses a specific verb (list) and resource (identity providers), and distinguishes from siblings by referencing related tools like keycloak_idp_get.

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?

Explicitly guides the agent to use this tool before calling keycloak_idp_get, keycloak_idp_mappers_list, or keycloak_idp_delete. Also notes read-only and idempotent nature, providing clear context for when to use.

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, destructiveHint, and idempotentHint. The description reinforces these and adds the return format (JSON array of mapper definitions), which adds value beyond 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?

Three sentences, each earning its place: purpose, explanation, usage guidance and return type. No waste, 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 tool with one parameter, full annotation coverage, and a clear description of return type, the description is complete. It also provides usage order context.

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 covers 100% with a single alias parameter. The description adds context by stating the alias is from keycloak_idp_list and provides examples (e.g., 'google', 'corporate-saml'), significantly enriching the parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists mappers for a single identity provider by alias, with a specific verb and resource. It distinguishes itself from sibling tools by mentioning it is used after keycloak_idp_list or keycloak_idp_get.

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?

Explicitly says to use after keycloak_idp_list or keycloak_idp_get, providing clear context. Does not list alternatives explicitly, but the guidance 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?

The description restates the readOnlyHint and idempotentHint from annotations and adds behavioral detail: 'takes no parameters' and 'never modifies Keycloak'. This provides context 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 consists of two succinct sentences with no redundant information. It is front-loaded with the read-only nature and return type, followed by use case and parameter confirmation.

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 lists the specific fields returned (realm name, enabled state, flags, SSL requirement, session lifespans) and notes it returns a JSON object. Since there is no output schema, this adequately explains the return structure.

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 are no parameters, and the description explicitly states 'takes no parameters', which adds value for a tool with zero parameters. The baseline for no parameters is 4.

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 it returns a curated subset of the realm's configuration as a JSON object, listing specific fields. It uses a specific verb ('Get') and resource ('realm configuration'), and distinguishes from a full realm representation.

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 explicitly states to use this tool for inspecting security-relevant realm settings, implying an alternative (full realm representation) is not needed. It does not explicitly name sibling tools or provide exclusion criteria, but the guidance is clear and 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?

Annotations already declare readOnlyHint=true and idempotentHint=true; description adds return format details (JSON array with id, name, description) which is useful but not critical given the simple read 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?

Two sentences with front-loaded purpose and clear, efficient language; no unnecessary 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?

Despite no output schema, description explains return format and scope, fully covering what the tool returns and how it fits into broader workflows.

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?

No parameters, so baseline is 4; description correctly notes 'Takes no parameters' but adds no further semantics 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?

Clearly states 'lists all realm-level roles' with explicit distinction from client roles, defining a specific verb and resource.

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?

Explicitly instructs to use before assigning a role with keycloak_user_role_assign and directs to keycloak_client_roles_list for client roles, providing clear when-to-use and alternatives.

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, destructiveHint, idempotentHint; description adds that it takes no parameters and never modifies Keycloak, providing minor additional context.

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?

Three concise sentences, front-loaded with 'Read-only', no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, output, idempotency, and alternative tool; complete for a simple no-parameter read 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?

No parameters, and description correctly states 'Takes no parameters', which is clear and sufficient.

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 it returns a small JSON summary with the 'keycloakVersion' field, distinguishes from realm-specific settings tool.

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?

Explicitly says to use for quick connectivity/version check, and directs to keycloak_realm_get_config for realm-specific settings.

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 description complements the annotations by detailing the return behavior (confirmation or explanation for failure) and confirming idempotency. While it lacks explicit mention of error handling (e.g., exceptions), it sufficiently discloses what happens when the user, client, or role is not found. Annotations already mark it as non-destructive and idempotent, so the description adds value without 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?

The description is three sentences long, each earning its place. The first sentence states the core purpose and distinction, the second explains idempotency, and the third covers return behavior. No extraneous information, and the most important facts are 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 the tool's low complexity (three required parameters, no output schema, no nested objects), the description covers all essential aspects: purpose, scope, idempotency, prerequisites, failure cases, and return value. It also references sibling tools for listing and verification. No gaps remain for an agent to use 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?

With 100% schema coverage, the schema already documents all three parameters thoroughly. The description adds contextual value by explaining idempotency and the prerequisite that the role must exist, plus useful cross-references to sibling tools. This extra context justifies a score above the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool grants a single client-level role to a user, explicitly distinguishing it from realm roles. The title 'Assign a client role to a user' and the first sentence provide a specific verb-resource pair, and the sibling context includes both keycloak_user_role_assign (realm roles) and keycloak_user_client_role_unassign, making differentiation 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 description explicitly says when to use (for client-level roles, not realm roles) and provides concrete pre- and post-steps: list candidates with keycloak_client_roles_list and verify with keycloak_user_client_roles_get. It also notes the role must already exist and that the operation is idempotent, guiding proper usage.

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 indicate read-only, non-destructive, idempotent. Description adds return format (JSON array of roles with id, name, description) and error message for missing client, providing context beyond 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?

Two concise sentences, each carrying essential information. Front-loaded with purpose and key characteristics. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and lack of output schema, description covers all needed aspects: purpose, read-only nature, input params, output format, error case, and relationship to other tools.

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 descriptions are already clear and comprehensive (100% coverage). Description adds extra context that userId and clientId are UUIDs, not usernames/names, and explains scoping. Adds value beyond 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?

Description clearly states it lists client-level roles for a specific user and client, not realm roles. Distinguishes from siblings like keycloak_user_roles_get and relates to assign/unassign 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?

Explicitly advises use before granting or revoking roles, and directs to keycloak_user_roles_get for realm-wide assignments. Provides clear when-to-use and alternatives.

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 annotations (destructiveHint=true), the description reveals the confirmation gate ('will not proceed unless confirm is true') and describes the return behavior (confirmation or explanation). This adds valuable context for safe usage.

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 paragraph of 4 sentences, front-loading the destructive purpose. Every sentence adds essential information 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?

Given no output schema, the description fully covers return values. It also addresses prerequisites, alternatives, and failure cases, making it contextually complete for a destructive tool with a confirmation gate.

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?

With 100% schema coverage, the description still adds value by explaining the confirm parameter's gatekeeping role and clarifying that role is a name, not an ID. This enriches the schema descriptions.

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 'revokes' and the resource 'a single client-level role from a user', and explicitly distinguishes it from realm roles ('this is not a realm role'). This sets it apart from sibling tools like keycloak_user_role_unassign.

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?

Provides explicit when-to-use: suggests using keycloak_user_client_roles_get first, and for realm roles directs to keycloak_user_role_unassign. Also states the confirmation requirement, guiding the agent on prerequisites.

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?

Discloses beyond annotations: indicates it's a write operation (non-read-only), not destructive, non-idempotent (consistent with idempotentHint=false), and adds that it doesn't set passwords or send emails. Annotations are minimal but description fully covers behavioral 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?

Three sentences, each adding value. Front-loaded with main action. No redundancy. Perfectly sized for the information needed.

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 tool's simplicity (4 params, no output schema), the description is fully complete. It covers creation, post-creation steps, idempotency, and references sibling tools. No 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 100%, so baseline is 3. The description repeats parameter defaults (enabled true, emailVerified false) but adds no new semantics beyond the schema. It mentions username uniqueness but that's already in schema. No additional param-specific context needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a new realm user and returns a confirmation message. It distinguishes from siblings by noting it does not set a password (use keycloak_user_reset_password) and is not for updates (use keycloak_user_update).

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?

Explicitly states when to use (create user), what it does not do (set password, send email), provides alternative (keycloak_user_reset_password for credentials), and warns about non-idempotence causing conflicts.

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 description fully discloses behavior: irreversible deletion, return messages ('User deleted' or 'Not deleted: <reason>'), and safety checks (username match, confirm required). Annotations already indicate destructiveHint=true, and description adds valuable context without 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?

The description is concise, using three sentences to convey all key information: destructive effect, return messages, safety guards, prerequisites, and alternative. Every sentence adds 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 the tool's destructive nature and multiple parameters, the description covers all essential aspects: return values, safety mechanisms, lookup steps, and alternatives. No output schema exists, so the description compensates 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?

Schema coverage is 100%, but the description adds significant meaning: explains that id is obtained from search, username serves as a safety check, and confirm defaults to false. This goes beyond the schema's basic descriptions.

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 explicitly states that the tool permanently removes a user, using the verb 'deletes' and highlighting its destructive nature. It distinguishes from alternatives like keycloak_user_set_enabled, making purpose 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 description provides clear guidelines: use keycloak_user_get or keycloak_user_search first to obtain id and username, and consider keycloak_user_set_enabled as a non-destructive alternative. It also explains the confirm parameter safety guard.

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, destructiveHint=false, idempotentHint=true. The description adds value by specifying the exact return format (JSON with id, username, email, enabled) and the 'User not found' response, plus confirming idempotency.

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, front-loaded with 'Read-only' and no unnecessary words. Every sentence provides essential 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 fetch tool with one parameter and annotations covering safety, the description fully explains the return value, failure behavior, and usage hint. No output schema needed given the clear textual description.

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 a single 'id' parameter. The description adds context by specifying it's a UUID and directing to keycloak_user_search to obtain it, plus an example UUID, adding 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 clearly states 'fetches a single realm user by id' with specific return fields (id, username, email, enabled flag) and the 'User not found.' case. It distinguishes from keycloak_user_search by specifying the input is an id, not username/email.

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 explicitly advises to use keycloak_user_search first if only username or email is known, guiding the agent on when to use this tool versus alternatives.

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, destructiveHint, and idempotentHint. The description reinforces these and adds return structure details ('JSON array of group objects'). This extra context helps the agent understand what to expect, beyond 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 short, purposeful sentences, each adding unique value: safety traits, core function, prerequisite, output format. No fluff, front-loaded with key characteristics.

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 tool with one parameter and no output schema, the description adequately covers purpose, prerequisite, and return format. It lacks mention of edge cases (e.g., empty list, invalid user ID) but is sufficient for typical usage.

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 the description adds no new information about the userId parameter beyond what the schema provides. The hint to resolve the user ID is a usage guideline rather than parameter semantics. 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 states the tool lists groups for a user, with explicit mention of being read-only and idempotent. It specifies the output format (JSON array of group objects with id, name, path) and distinguishes from sibling group/user tools by focusing on user-group membership.

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?

Provides clear prerequisite guidance: 'Resolve the user ID first with a user listing tool.' This tells the agent when and how to prepare. However, it does not explicitly state when not to use this tool or mention alternatives, so it misses some exclusionary 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?

Beyond annotations, the description adds details: destructive nature, confirmation requirement, return messages, user account remains enabled, and effective idempotence. It even explains the behavior if sessions are already revoked.

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?

Description is well-structured and front-loaded. While slightly long, every sentence serves a purpose, explaining action, effect, prerequisites, and alternatives. Could be trimmed slightly but effective.

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 2 parameters, no output schema, the description covers purpose, parameters, return values, and edge cases (idempotency). It's sufficiently complete for an agent to use 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 coverage is 100%, so baseline 3. Description adds meaning: id is from keycloak_user_search, confirm must be true to proceed. Adds context beyond parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Destructive write that revokes all active sessions for a user, forcing them to re-authenticate'. It distinguishes from siblings like keycloak_user_set_enabled and keycloak_user_sessions_list by specifying what this tool does vs 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?

Explicitly states when to use (for logout) and provides alternatives: 'use keycloak_user_set_enabled to block future logins or keycloak_user_sessions_list to inspect sessions first'. Also explains the required confirmation with confirm=true.

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 provide destructiveHint and idempotentHint. Description adds specific return messages on success/failure, the confirmation requirement, and that it invalidates the previous password, adding value beyond 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?

Two sentences with a usage tip, front-loaded with key information. Every sentence serves a purpose, no 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?

Given 4 parameters and no output schema, the description adequately explains return behavior, required confirmation, and typical usage context (after user creation). Complete for the tool's complexity.

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%, so description adds marginal value for parameters. It explains the confirm parameter's role but does not describe id or password beyond the schema. 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?

Description clearly states it is a 'Destructive write that overwrites a user's password' with the supplied value, specifying the verb and resource. It distinguishes from sibling tools by mentioning common usage after keycloak_user_create and noting non-idempotency.

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?

Explicitly states the need for confirm=true and that it is commonly used after user creation. Does not explicitly mention alternatives, but the tool is unique among siblings.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds context by confirming idempotency explicitly ('assigning a role the user already has succeeds without changing anything') and describes the return behavior (confirmation or failure message). It also discloses the precondition that the role must exist, which is beyond annotations but not contradictory.

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, highly efficient. The first sentence conveys the core action, scope, and idempotency. The second sentence covers preconditions, alternative tools, and expected return. No extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 required params, no output schema), the description covers all essential aspects: what it does, scope (realm role vs client role), idempotency, preconditions, return format, and related tools. It is complete for an agent to understand when and how to invoke it 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?

The input schema covers both parameters with full descriptions (100% coverage). The description does not add new semantic information about the parameters beyond what the schema already provides, such as clarifying that userId is a UUID and role is a realm role name. Thus, 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 clearly states 'grants a single realm-level role to a user (not a client role)', immediately distinguishing the tool from role assignment for client roles and specifying the scope as realm-level. The verb 'grants' is specific and the resource (realm role to a user) is 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 explicit guidance: it notes this is for realm roles, not client roles, and suggests listing candidates with keycloak_role_list and verifying current assignments with keycloak_user_roles_get. It implies when not to use (for client roles) but does not explicitly mention the sibling keycloak_user_client_role_assign, which would be ideal. The context of idempotency and precondition (role must exist) 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?

Annotations already provide readOnlyHint, destructiveHint, and idempotentHint. The description reinforces read-only nature and adds valuable context about the return format (JSON array with id, name, description), which goes beyond 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 concise at three sentences, front-loaded with 'Read-only', and every sentence provides essential information: purpose, when to use, and return format.

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 tool with one parameter, annotations, and no output schema, the description covers all necessary aspects: behavior, use cases, return structure, and sibling differentiation.

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 fully describes the userId parameter with 100% coverage. The description does not add any additional meaning or constraints 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 clearly states it is a read-only operation to list realm-level roles for a single user, and explicitly distinguishes from client roles via reference to sibling tool keycloak_user_client_roles_get.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool (inspect before grant/revoke) and when not to (use keycloak_user_client_roles_get for client-scoped assignments), naming alternative tools directly.

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 destructiveHint=true and readOnlyHint=false; description adds that explicit confirmation is required (confirm=true) and explains return values, going beyond 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?

Two sentences cover purpose, usage, behavior, and return. Front-loaded with key information, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but description explains return values. Covers all needed context: purpose, prerequisites, alternatives, confirmation gate, and error cases.

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 provides full descriptions for all 3 parameters. Description reiterates the confirmation requirement but adds no new semantic detail beyond what is already in 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?

Clearly states it revokes a single realm-level role from a user, differentiating from client roles and using a specific verb (revokes) and resource (realm-level 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?

Explicitly advises using keycloak_user_roles_get first and directs to keycloak_user_client_role_unassign for client roles, providing clear when-to-use and alternatives.

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 indicate readOnlyHint, destructiveHint, idempotentHint. Description adds read-only, pagination cap, combined filters, first page behavior, beyond 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 concise sentences, front-loaded with key attribute, each sentence adds value 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?

Given no output schema, description specifies return fields. Covers pagination, filter behavior, and use case for id discovery. Complete for a search 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 coverage is 100% with detailed parameter descriptions. The description adds higher-level usage context like filter combination and pagination defaults, which augments schema but schema already provides full parameter semantics.

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 it is read-only, searches users, returns a JSON array with specific fields (id, username, email, enabled flag). Distinguishes from siblings by mentioning use for discovering user id before id-based 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?

Explicitly says 'Use this to discover a user's id before calling id-based tools' and explains all filters are optional and combined, pagination cap of 500, and default behavior.

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?

Discloses write operation, non-idempotency, and prerequisite of valid email address, adding context beyond 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?

Two concise sentences covering purpose, behavior, usage context, and alternative. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given simple schema and no output schema, description covers all necessary aspects: operation type, prerequisites, idempotency, return value, and parameter details.

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?

Adds value over schema by specifying that actions must contain at least one valid key and that id can be obtained from keycloak_user_search.

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 specifies the verb (send action email), resource (user), and action (email with required actions). Distinguishes from sibling tool keycloak_user_reset_password.

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?

Explicitly states when to use (self-service flows) and when not to (set password directly), providing a clear 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context: 'never changes any state' and 'repeated calls reflect only sessions that are still active', confirming idempotency and dynamic behavior. No 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?

Two sentences only: first describes output, second provides usage guidance. No redundant or filler content. Extremely 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 tool with one required parameter and no output schema, the description fully covers input, behavior, output format (JSON array), and relationship to other tools. The agent has all necessary information.

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 detailed description of the 'id' parameter. The main description adds value by stating the parameter is required and obtained from keycloak_user_search, which goes beyond the schema's basic 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 clearly states the tool returns a JSON array of a user's currently active sessions, distinguishing it from sibling tools like keycloak_user_logout (revocation) and keycloak_user_search (user lookup). The verb 'list' combined with resource 'user sessions' is specific.

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?

Explicitly advises using this tool to inspect sessions before deciding to revoke access with keycloak_user_logout, providing clear context and a specific alternative. Also notes idempotency, implying safe repeated calls.

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?

Adds context beyond annotations: confirms account is not deleted, sessions are not revoked, and operation is idempotent. No contradictions with 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?

Three concise sentences with clear purpose, side effects, and alternatives. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 required params and no output schema, the description fully covers usage, behavior, and side effects. No missing information for 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?

Adds value beyond schema by noting the id should be obtained from keycloak_user_search and explaining the enabled parameter's effect on account state. Schema coverage is 100% but description enriches understanding.

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 it enables or disables a single user account by id and returns a confirmation message. It distinguishes from siblings like keycloak_user_logout and keycloak_user_delete.

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?

Provides explicit guidance on when to use (enable/disable) and explicitly contrasts with logout and delete for session termination and account removal. Also notes idempotency.

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 description goes beyond annotations by clarifying partial update semantics (only supplied fields changed, omitted left untouched) and idempotency in plain language. Annotations already indicate idempotentHint=true, but the description adds valuable context.

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 three sentences, front-loaded with the main purpose, and contains no extraneous information. 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?

Given no output schema, the description mentions it returns a confirmation message. It covers partial update, idempotency, and usage guidance, making it complete for the tool's complexity (5 simple params).

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 each parameter having a clear description (e.g., 'New email address... Optional; omit to leave the email unchanged.'). The description adds extra value by explaining the overall behavior of optional parameters, meriting a score above baseline 3.

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 explicitly states it updates existing user profile fields and returns a confirmation message, using a specific verb and resource. It distinguishes from sibling tools by mentioning keycloak_user_get and keycloak_user_reset_password.

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 guidance: use keycloak_user_get first to read current values, and keycloak_user_reset_password for credentials instead. It also explains idempotent behavior, helping the agent decide when 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.