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

No annotations, so description carries the burden. It implies a safe read operation but does not specify performance, whether disabled users are included, or if the count is cached. Lacks detail beyond the obvious.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no extraneous text. 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 tool with no parameters and an output schema available, the description sufficiently defines the purpose. The output schema likely explains the return format. Complete for this simple case.

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%. The description adds no parameter information, but none is needed. 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 action ('get') and the resource ('total user count in the realm'). It distinguishes from sibling tools like 'search_users' which returns user details or 'get_user' which returns a single user.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., counting via search_users). For a simple tool, some context about use cases (e.g., quick overview vs detailed search) would be helpful.

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

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

No annotations exist, so the description carries the full burden, and it delivers: it discloses output tiers (CRITICAL/WARNING/OK), default thresholds, scoping to since_hours, the independent brute-force and spray-check rules, and the caveat that only accounts in the Spray check list may be called breached. It even explains the evidence tuple shape.

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?

Although longer than average, the description is well structured with bullets, sections, and an Args block. It front-loads the purpose, groups checks logically, and every sentence adds meaningful information about thresholds, defaults, output tiers, or routing to spray_check.

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 two parameters, an existing output schema, and non-trivial detection logic, the description is complete: it covers all checks, thresholds, defaults, output tiers, and the exact semantics of the two arguments. It also points to spray_check for further tuning and row details, so an agent has everything needed to invoke and interpret results.

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 0%, and the description fully compensates by explaining both parameters semantically: since_hours is the look-back window with a default and morning-run rationale, while ip_failure_threshold is the single-IP failure count that triggers a WARNING. This goes well beyond the bare integer 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 opens with a specific verb and resource: 'Run a morning Keycloak health check.' It then enumerates the exact checks, making clear this is an aggregate tool that sits above granular siblings like get_login_stats, get_session_stats, and get_admin_events, and it explicitly references spray_check for the spray-detection portion.

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

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

It gives clear usage context as a morning health check, with since_hours defaulting to 18 to approximate a previous-day window for a 09:00 run. It also directs users to spray_check when they need the full row shape or want to widen the window/tune thresholds, but it does not explicitly enumerate when to prefer the granular sibling tools over this aggregate.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the KEYCLOAK_DEADLINE time bound (default 45s), that results may be partial with a 'PARTIAL RESULT' prefix, that counts become a lower bound, and the correct retry strategy. This is exactly the kind of non-obvious behavior an agent needs before calling.

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?

Front-loaded with the purpose, then a well-structured args list. The deadline paragraph is slightly long but every sentence (partial results, retry advice, trigger cause) earns its place. Minor verbosity only.

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 5-param detection tool with an output schema already covering return values, this description covers purpose, all parameters, time-bounding behavior, and failure handling. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it documents all five parameters: date formats (YYYY-MM-DD), defaults, the meaning of threshold/window_seconds, and 'Use 0 for all' for top. It fully fills the gap left by the schema.

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

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

States a specific verb+resource+scope: 'Detect users with rapid repeated logins (possible redirect loops).' This is immediately distinguishable from siblings like spray_check and get_login_failures_by_ip, which target different attack patterns.

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

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

Usage is implied by the detection description, and it gives good operational guidance ('Call again with a narrower window instead of retrying'), but it never explicitly says when to choose this over a sibling like spray_check or get_login_stats. No when-not or alternative routing is provided.

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

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

No annotations are provided, so the description carries the burden of disclosure. It discloses meaningful behavioral context: admin events reflect service-account/admin operations, the default date_from is last 24h, and max_repr semantics. It does not explicitly discuss read-only status or auth requirements, but 'Get' plus the audit-query framing make these less critical.

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 front-loaded with the purpose paragraph and followed by a compact, scannable Args list. Every sentence adds value; there is no padded language or repetition of the input schema.

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

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

The tool has 7 parameters and zero schema-level parameter descriptions, but the text covers all seven, provides defaults and enums in prose, and gives a why/when not to use. Because an output schema exists, not explaining return values is acceptable, and there is no significant explanatory gap.

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 provides only parameter names and defaults (0% description coverage), so this description is the only source of parameter meaning. The Args section thoroughly defines every parameter, including enum-like values for operation_types and resource_types, a resource_path example, date format, and default behavior for max_results and max_repr.

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

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

The description opens with a specific verb + resource ('Get KeyCloak admin events') and immediately clarifies the scope: changes performed via the Admin REST API. It explicitly distinguishes these from user events and references sibling 'get_events', so the agent can disambiguate among similar 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?

It provides an explicit 'Use this when...' trigger: when UPDATE_PROFILE in get_events is empty but an attribute is known to have changed. It also differentiates admin events from user events, giving clear selection guidance for this tool versus related event-retrieval tools.

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

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

No annotations are provided, so the description carries full burden. It states the operation is a 'check' (implying read-only) but does not disclose potential side effects, permissions, or error handling. Lacks detail on output behavior, though output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: one for purpose, one for parameter documentation. No redundant words; front-loaded with actionable 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 having an output schema, the description does not clarify what 'locked' means (e.g., duration) or how results map to tool selection among similar siblings. Adequate but incomplete.

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 0%, so description must compensate. It adds 'Exact username (email)' to the parameter, clarifying expected format, but no examples or constraints. Minimal added 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?

The description uses the verb 'check' and specifies the resource 'if a user is temporarily locked due to brute force detection,' clearly distinguishing it from sibling tools like get_user or get_login_stats.

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

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

The description implies when to use (to check lock status) but does not provide explicit guidance on when not to use or alternatives among siblings like get_login_failures_by_ip.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses that the tool returns an allowlist rather than raw client representation, explains that attributes and protocolMappers are omitted to keep credential-shaped data out of output and LLM context, and notes that flow IDs are resolved to aliases. This is far beyond the minimum disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then builds detail in a logical order: output shape, security rationale, domain semantics, and the argument definition. Every sentence adds actionable context rather than repeating schema or title 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 single-parameter read tool, the description covers the key selection and invocation facts: what the tool returns, why certain fields are omitted, how flow overrides are presented, and which identifier to pass. The presence of an output schema means the explicit allowlist fields need not be enumerated in prose.

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 only says client_id is a string, but the description adds the crucial distinction: 'The clientId (not the internal UUID).' This prevents a likely mis-invocation and gives the agent exactly the semantic needed for correct lookup.

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 opening sentence states a specific verb and resource: 'Show one client's configuration, including its authentication flow overrides.' It clearly distinguishes from siblings like list_clients and get_client_sessions by emphasizing the singular client and the configuration focus.

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 makes the scope clear—'one client's configuration'—which implies this is for retrieving a single client's full config rather than listing clients or sessions. However, it does not explicitly name alternatives or say when not to use this tool, so there is room for sharper routing 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?

No annotations are present, so the description must disclose behavioral traits. It only mentions 'active sessions' but omits details like data freshness, pagination, error handling, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is succinct with two sentences plus an Args list. Every phrase adds value, and the structure is 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?

Given the absence of annotations and output schema visibility, the description covers parameter semantics but lacks behavioral context. With two simple parameters and an output schema present, it is minimally complete but could elaborate on result behavior.

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 0%, but the description provides examples for client_id ('xflow', 'shadowserver') and clarifies max_results default (100). This adds meaningful context beyond the bare 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 verb 'Get' and the resource 'active sessions for a specific client (SP)'. It distinguishes from sibling tools like get_user_sessions by specifying client sessions, making the purpose 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?

No guidance is provided on when to use this tool versus alternatives such as get_user_sessions or get_session_stats. Agents have no basis for tool 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?

With no annotations, the description carries the full burden. It explains parameter behaviors (e.g., date_from defaults to last 24h, username resolved internally, ip_address is client-side filter). However, it does not disclose whether the operation is read-only, authentication requirements, or rate limits, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with a clear lead sentence followed by a detailed args list. All sentences are informative, but the list format is slightly verbose. It is front-loaded with the purpose, which is good.

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 covers parameters well and output schema exists, so return values need not be explained. However, it lacks guidance on when to use this tool among many similar siblings and does not mention any limitations or edge 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 description coverage is 0%, so the description must compensate. It explains all 7 parameters with additional context such as default values, internal resolution, and filter nature, providing significant value beyond the bare 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 'Get KeyCloak events with optional filters', using a specific verb and resource. It does not explicitly distinguish from sibling tools like get_admin_events, but the name and context make the purpose reasonably 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 no explicit guidance on when to use this tool versus alternatives such as get_admin_events or get_password_update_events. It lists filters but does not explain the appropriate context or conditions for selecting this tool.

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

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

No annotations are provided, so the description carries the full burden, and it delivers substantial context: the wall-clock deadline (KEYCLOAK_DEADLINE, default 45s), the distinction between events_capped (whole result incomplete) and truncated (timeline-only trim), and empty-input handling. It stops short of permission/auth requirements, but the pagination and deadline semantics are unusually well disclosed.

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?

Well front-loaded — purpose, sibling comparison, and use case precede the return-shape detail — and every section earns its place given there is no output schema. It is nonetheless very long, with the extensive per-key Returns block dominating the text; that length is defensible only because it has nowhere else to live.

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

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

With no output schema and 0% parameter coverage, the description is the sole carrier of both argument and return semantics, and it covers the fixed-shape dict, the capped/incomplete flags, and the deadline-driven lower-bound behavior. Nothing an agent needs to call this correctly or interpret the result is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for every parameter: ip_address with IPv6 normalization details, event_types with default and a widening example, date_from default (last 24h), date_to open-ended semantics, and max_timeline default/<=0 behavior. This is exactly the compensating detail a low-coverage schema needs.

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

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

States a specific verb+resource ('Exhaustive investigation of all activity from one source IP address') and immediately distinguishes itself from the sibling get_events(ip_address=...) by explaining the full-pagination behavior. An agent can tell it apart from get_login_failures_by_ip without opening either schema.

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

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

Explicitly names when to use it (brute-force / credential-stuffing / shared-workstation investigations) and the sibling workflow that leads here ('where get_login_failures_by_ip told you which IP to look at'). It also explains the alternative and its limitation (get_events filters a single page and can miss activity).

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses the KEYCLOAK_DEADLINE timeout (default 45s), that results are truncated with counts becoming a lower bound, that the result is prefixed with a 'PARTIAL RESULT' warning, and the correct retry strategy. This is non-obvious failure-mode and output-shape information an agent could not get from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed by the deadline/partial-result caveat and a compact Args block. The multi-sentence timeout passage is slightly verbose but each sentence carries actionable content, and the Args block adds real value given the empty schema descriptions.

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 3-parameter, zero-annotation tool with an output schema present, the definition covers the main behavioral risk (timeout/partial results) and the parameter semantics. It omits permission/auth requirements and any note on how the per-IP breakdown is ordered or bounded by top, but these are minor gaps given an output schema exists.

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 0%, so the description must compensate and largely does: it supplies the format (YYYY-MM-DD) for date_from/date_to, the semantics of an empty date_to ('all'), the 24h default for date_from, and clarifies that top is the number of top IPs to show. All three parameters are covered, though the interaction between date_to empty and date_from default is not fully spelled out.

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

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

States a specific verb and resource with an explicit aggregation dimension: 'login failure statistics broken down by source IP.' This is clearly distinguishable from siblings like get_login_stats_by_client and get_ip_activity, though it never names those alternatives directly, so sibling routing is left to inference rather than stated.

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

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

Gives concrete condition-based guidance for the partial-result case: a wide window on a busy day triggers the deadline, and the correct recovery is to re-call with a narrower window rather than retry. It does not, however, say when to prefer this tool over the other login/client/IP statistics 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?

No annotations are provided, so the description carries the full burden, and it delivers real behavioral context: a 45s deadline, partial results returned as a lower bound, and an explicit 'PARTIAL RESULT' warning marker. It omits auth/permission requirements, but the timeout semantics are the key non-obvious trait and are well disclosed.

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?

Front-loads the purpose, then the timeout behavior, then args — a logical order with no filler sentences. Slightly verbose with env-var names, and the Args block restates parameter names already in the schema.

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?

An output schema exists, so return-value documentation is not needed. The description covers purpose, defaults, and the failure mode adequately; the main omission is routing guidance relative to the many sibling stats 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 description coverage is 0%, so the description must compensate, and it does: date_from defaults to the last 24h (KEYCLOAK_DEFAULT_DATE_FROM_HOURS) and empty date_to means 'all'. Format (YYYY-MM-DD) is also stated. Minor gap is that the interaction between the two dates is not explained.

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

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

States a specific verb and resource (login success/failure statistics) plus a scope note about pagination. However, it never distinguishes itself from close siblings like get_login_stats_by_client, get_login_stats_by_hour, or get_login_failures_by_ip, which an agent must choose between.

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

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

Gives solid operational guidance for the timeout case (call again with a narrower window rather than retrying), but offers no guidance on when to pick this aggregate tool over the by-client, by-hour, or by-IP 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?

With no annotations, the description carries the full burden and does well: it discloses the KEYCLOAK_DEADLINE time bound, that counts become a lower bound on truncation, and that output is prefixed with a "PARTIAL RESULT" warning. It omits auth/permission requirements, but for a read-only stats tool that gap is minor.

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?

Purpose is front-loaded in one line, the time-bound caveat follows, and the Args block is compact. Nothing is filler, though the deadline paragraph could be trimmed by a sentence without losing meaning.

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?

An output schema exists so return structure needn't be restated, and the description covers the non-obvious failure mode (partial results under deadline). Missing only permission/scope framing and explicit sibling routing; otherwise complete for a 2-param stats tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: date_from gets a format (YYYY-MM-DD) and a default (last 24h via KEYCLOAK_DEFAULT_DATE_FROM_HOURS), and date_to gets a format plus the "empty for all" semantics. The "empty for all" wording is slightly ambiguous but the essential semantics are covered.

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

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

States a specific verb+resource ("Get login statistics") plus the aggregation dimension ("broken down by client (SP)"), which is exactly what separates it from siblings get_login_stats and get_login_stats_by_hour. An agent can route to it without opening the schema.

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

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

Gives useful operational guidance for the timeout case ("call again with a narrower window instead of retrying") and explains what triggers a partial result. It never says when to prefer this tool over get_login_stats or get_login_stats_by_hour, so the alternative-selection guidance is only implied by the breakdown dimension.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses a hard deadline (KEYCLOAK_DEADLINE, default 45s), partial results with a 'PARTIAL RESULT' warning, counts being a lower bound, the trigger condition (wide window on a busy day), and the recommended recovery action. This is rich behavioral context that an agent needs to interpret results correctly.

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?

Front-loads the purpose, then adds a focused behavioral block, then an Args section. Every sentence earns its place, and the structure makes the critical timeout behavior easy to find.

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 annotations, an output schema (so return values need not be explained), and 0% schema description coverage, the description is nearly complete: it covers purpose, timeout behavior, and both parameters. The main gap is the absence of sibling-selection guidance, but for calling the tool correctly, an agent has what it needs.

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 0%, so the description must compensate. It does by documenting the date format (YYYY-MM-DD), the default for date_from (last 24h via KEYCLOAK_DEFAULT_DATE_FROM_HOURS), and the meaning of an empty date_to ('for all'). The only slight ambiguity is that 'Empty for all' could be clearer, but overall it supplies the missing 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?

States a specific verb, resource, and granularity ('login statistics broken down by hour') that distinguishes it from the aggregate get_login_stats and the by-client variant. However, it does not explicitly name any sibling tool, so it relies on the agent to infer the difference from the name alone.

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 retry guidance for partial results ('call again with a narrower window'), but gives no guidance on when to use this tool versus alternatives like get_login_stats or get_login_stats_by_client. There is no explicit selection criteria or exclusion criteria.

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?

No annotations exist, so the description must carry the full burden. It reveals parameter behavior (date range, default) but omits traits like read-only nature, rate limits, or response format. It partially covers behavioral 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 concise: one line for purpose followed by parameter documentation. It is front-loaded and efficient, though the parameter section is a bit verbose with repetition of 'Args:' and parameter names.

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 covers parameter details and purpose but lacks context about the tool's scope (e.g., realm-wide vs user-specific) and does not mention that the tool is read-only. With an output schema present, return values are not required, but additional behavioral context would improve completeness.

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 0% schema coverage, the description compensates by specifying date format (YYYY-MM-DD) and defaults for date_from and max_results. It adds meaning beyond the schema's basic type/default fields, though the meaning of max_results is not fully explained.

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 retrieves 'password update events', a specific resource. The name and description differentiate it from sibling tools like 'get_events' (generic) and 'get_admin_events'.

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

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

The description provides parameter defaults and date format but does not explicitly state when to use this tool versus alternatives. The usage context is implied by the tool's name and purpose, not explicitly guided.

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 implies a read-only operation but does not explicitly disclose behavioral traits such as permissions, side effects, or rate limits. With no annotations, it partially meets the burden but lacks detail.

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 sentence with no wasted words. It is front-loaded and efficiently conveys the tool's 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 the tool's simplicity (no parameters, output schema exists), the description is fully complete. It tells the agent exactly what the tool does, and the output schema provides 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?

The tool has no parameters, so the description does not need to add meaning beyond the schema. Baseline score of 4 is appropriate as the schema already covers everything.

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 clearly identifies the resource 'realm-level roles', making the purpose unambiguous. It distinguishes itself from sibling tools like 'list_clients' or 'list_user_groups'.

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

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

No guidance is provided on when to use this tool versus alternatives. The description simply states what it does without any when-to-use or when-not-to-use 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?

The description declares the tool is read-only and details exactly what it reports (brute force detection, password policy, browser headers) without side effects, fully transparent given no 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 well-structured with bullet points, but slightly verbose; still concise enough to be 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?

Given zero parameters and an output schema, the description fully explains what the tool returns and its purpose, including usage context relative to siblings.

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, baseline 4. The description adds no parameter info, but none is 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 it shows realm security-defense settings (read-only) and distinguishes from sibling get_brute_force_status by noting it reports policy configuration, not runtime state.

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

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

It explicitly says to use this tool to verify brute-force protection is enabled and configured, and contrasts with get_brute_force_status for runtime state, 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?

With no annotations, the description must fully disclose behavioral traits. It only states the basic purpose without mentioning whether the count is real-time, cached, scoped to a time range, or requires specific permissions. This leaves behavioral uncertainty.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that effectively communicates the tool's function with no extraneous words. It is 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 simple nature of the tool (no parameters, has output schema), the description is minimally adequate. However, it lacks details such as whether counts are for all clients or filtered, time scope, and how results are returned, which would be helpful for full understanding.

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

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

The tool has no parameters, and schema coverage is 100%. The description adds no parameter details because none exist. The baseline for zero parameters is 4, and the description is clear about what the tool does, justifying the score.

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 'Get active session count per client' clearly states the verb 'Get' and the resource 'active session count per client', which distinguishes it from sibling tools like get_client_sessions or get_login_stats. It is specific and 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?

No usage guidance is provided. The description does not indicate when to use this tool versus alternatives such as get_client_sessions or get_login_stats_by_client, nor does it specify prerequisites or limitations.

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

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

With no annotations, the description discloses key behaviors: N+1 queries, slowness on large realms, error handling for credential lookup failures, and short-circuiting via max_users. It provides sufficient behavioral context for an agent.

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 well-structured with front-loaded purpose, then performance and parameter details. While somewhat lengthy, every sentence adds value. Minor redundancy could be trimmed.

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 annotations and 0% schema coverage, the description covers purpose, performance, parameter behavior, and error handling. Output schema exists, so return value explanation is not needed. The tool is well-described for agent use.

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 0%, and the description fully explains all three parameters: enabled_only, list_users, and max_users. It adds important details like default fallback to KEYCLOAK_MAX_USERS and sample coverage when capped.

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 reports the count of users with TOTP configured across the realm. It uses specific verbs ('Report') and resource ('users with TOTP'), and distinguishes from sibling tools like 'count_users' and 'get_user_credentials'.

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

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

The description explains when to use this tool (to get TOTP user count), but lacks explicit alternatives or 'when not to use' guidance. However, the performance warning and parameter 'max_users' provide 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?

With no annotations provided, the description carries the full transparency burden. It goes beyond a simple getter by disclosing the extra by-ID lookup, the omission of attributes in the search endpoint, and the credential-key blocking safety net. It does not cover all possible error cases, but the disclosed behavior is substantial.

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 structured with a crisp one-sentence summary followed by a necessary behavioral clarification paragraph and an Args block. The detail about the whitelist and credential-blocking is somewhat long but earns its place by explaining non-obvious tool behavior.

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

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

The tool has an output schema, so return-value documentation is not required. The description covers the key contextual points: exact-match lookup, custom attribute handling, and safety filtering. It is adequate for selecting and invoking the tool, though it leaves error behavior unspecified.

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 0%, but the description compensates with an explicit Args section: 'username: Exact username (e.g., user@example.com).' This adds format and exactness semantics that the bare schema lacks, though there is only one parameter to explain.

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 first sentence clearly states the action ('Get detailed user information') and the target ('by exact username (email)'). It is specific enough to distinguish from sibling tools like get_user_sessions or search_users, though it does not explicitly contrast with those alternatives.

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

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

The description implies the tool should be used when you have an exact username or email. It does not explicitly state when to prefer this over search_users or other lookup tools, nor does it mention exclusions or alternative tools.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses that the tool queries admin events scoped to users/{userId} with UPDATE/ACTION operations, explains default date-from behavior, and clarifies max_repr semantics. It does not mention authentication, rate limits, or pagination, but it gives strong operational detail for a read-only query tool.

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 well-structured: a one-sentence purpose, a brief context paragraph explaining why the tool exists relative to get_events, and a compact Args list. Every sentence adds value, and the format is easy to scan.

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 there is an output schema, the description need not explain return values. It covers purpose, scope, operation types, defaults, parameter semantics, and the key differentiator from get_events. This is complete for a focused admin-history query tool.

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

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

Schema description coverage is 0%, so the description must fully compensate. The Args section documents all five parameters with practical semantics: username is exact email, date_from defaults to last 24h, max_results defaults to 100, and max_repr values (0 omit, -1 full) are explained. This goes well beyond the bare 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 opens with a specific verb and resource: 'Get admin-side attribute change history for a single user.' It clearly distinguishes itself from siblings by contrasting with get_events, which only surfaces user-driven events, making the tool's unique purpose immediately understandable.

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

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

The description gives clear usage context by stating it is 'Intended for tracking custom attribute changes' written by admin API and explicitly notes these do not surface in get_events. It provides a when-to-use rationale and names the relevant alternative, though it does not exhaustively enumerate 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?

With no annotations, the description discloses that it is read-only ('Reads', 'does not create a session'), which is crucial for behavioral understanding. It does not detail error handling or permissions, but for a simple read operation this is adequate.

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, front-loaded with the main purpose, followed by a usage example, technical detail, and parameter description. Every sentence adds value with 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?

The tool is simple with one parameter well-described. An output schema exists (not provided), so return values need not be explained. Minor lack of error handling info, but overall sufficiently complete for its 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 description coverage is 0%, so the description must compensate. It adds meaning by specifying that 'username' must be an exact username (email), which is not in the schema. This fully clarifies the 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?

The description uses a specific verb 'List' and resource 'credential types configured for one user', giving examples and clarifying it's for checking a single user's MFA status. This clearly distinguishes it from sibling tools like search_users or 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 explicitly states to use this for checking a single user's MFA status, providing clear context. It does not give explicit exclusions or alternatives, but the use case is well-defined and sensible among the sibling tools.

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

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

No annotations provided, so description must carry behavioral disclosure. It does not mention whether the call is read-only, requires authentication, or handles missing users. Only the action is stated.

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?

Very concise—two sentences. Front-loaded with the main action. The 'Args' section is slightly redundant given the schema but provides useful extra detail.

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?

Tool has output schema, so return value details are not required. However, given low complexity, the description is adequate but could mention that only active sessions are returned.

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 0%, but description adds meaning by specifying 'Exact username (email)'. However, it does not clarify case sensitivity, format expectations, or error behaviors for invalid usernames.

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 'Get active sessions for a user', clearly specifying the verb and resource. It distinguishes from siblings like get_client_sessions and logout_user, though it could be more precise about the scope (e.g., active vs all sessions).

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

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

No guidance on when to use this tool vs alternatives like get_session_stats or when not to use it. Missing context about prerequisites or exclusion cases.

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

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

With no annotations provided, the description fully carries the burden. It discloses the OAuth2 Client Credentials Grant, cached client reuse, lightweight nature, exact return keys, value sets (e.g., 'status: healthy/degraded/error'), and even notes keycloak_version is None due to cost. This is exceptionally transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose, then usage, then return contract – well structured. However, the closing paragraph about READMEs is meta-commentary irrelevant to an AI agent invoking the tool, adding slight bloat. Otherwise, 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 having no output schema, the description fully specifies return keys, possible values, and meanings (including 'detail' for errors). It also covers deployment-specific fields like keycloak_url and realm. For a zero-parameter health check, this is complete and self-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?

The tool has zero parameters, and the schema confirms this. The description correctly doesn't waste space on parameter details. Per rubric, a 0-param tool gets a baseline of 4, and there is no additional semantic burden to meet.

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 'Report server version and KeyCloak backend connectivity / authentication' – a specific verb with a precise resource. It immediately distinguishes this from sibling tools (none of which are health/connectivity checks). The purpose is unambiguous and well-scoped.

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 when to call: 'at session start (or after a tool-call timeout)' and explains what it confirms. It also states what it does NOT do ('does NOT enumerate users, events, or sessions'), giving a clear when-not boundary. This fully satisfies the 'when/when-not' criterion.

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?

No annotations are provided, so the description carries the burden. It only states 'list all clients' with no mention of side effects, pagination, ordering, or rate limits. The existence of an output schema helps, but behavioral safety (read-only) is implied but not stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single, clear sentence that is front-loaded and contains no unnecessary verbiage. Every word earns its place.

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

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

For a simple list tool with no parameters and an output schema, the description is complete enough to inform the agent of the tool's purpose. The return structure is covered by the output schema.

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

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

There are zero parameters, so schema coverage is 100%. The description adds no parameter information, but since no parameters exist, the baseline of 4 applies. The description doesn't need to add more.

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 verb 'list', resource 'SAML/OIDC clients', and scope 'in the realm'. It is specific and distinguishes from sibling tools (no other list clients 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?

No guidance on when to use this tool versus alternatives. While no similar list client tools exist in siblings, the description does not provide context for when to use or not use it (e.g., if filtering 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?

No annotations are provided, so the description must convey behavioral traits. The description implies a simple read operation, but it doesn't disclose potential behaviors like pagination, rate limits, or required permissions. However, for a straightforward listing, it is minimally adequate.

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 extremely concise with only two sentences: the first states the purpose, the second lists the parameter and its meaning. 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 that there is an output schema (not shown), the description need not explain return values, but it lacks context on the scope of groups (e.g., all groups or filtered). It is minimally complete for a simple one-parameter 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 input schema has 0% description coverage, but the description adds crucial information: 'username: Exact username (email).' This clarifies the format of the parameter beyond the schema's type string, providing clear usage guidance.

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: 'List groups a user belongs to.' This is a specific verb-resource combination that distinguishes it from sibling tools like get_user or search_users, which focus on user details or search rather than 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?

The description provides no guidance on when to use this tool versus alternatives. For example, it doesn't mention when to use list_user_groups over get_user, or any prerequisites or context for calling 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?

With no annotations, the description carries full burden. It discloses only that group_name supports partial match and max_results defaults to 100, but does not mention read-only nature, permission requirements, or behavior on missing groups. It also does not describe the return structure, though an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is minimal and efficient, using two short lines for parameters. 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?

Given the tool's simplicity (2 params, output schema present), the description covers the essential parameters and their behavior. It could mention case sensitivity or result ordering, but overall it is sufficient for basic 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?

The description adds 'partial match' to group_name and clarifies max_results as a maximum limit, which goes beyond the bare schema and compensates for the schema's 0% description coverage.

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

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

The description uses a specific verb ('List') with a clear resource ('all users in a group'), and the parameter 'group_name' clarifies scope. It distinguishes itself from sibling tool 'list_user_groups' by focusing on users within a group rather than the groups themselves.

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

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

No explicit guidance on when to use this tool versus alternatives like 'search_users' or 'get_user'. The description provides no context or exclusions, leaving the agent to infer 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?

No annotations are provided, so the description carries the full burden. It clearly states the destructive effect ('removing all their active sessions'), which is transparent. However, it does not mention potential side effects like token invalidation or reversibility.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences: the first delivers the main action, the second documents the parameter. No wasted words, front-loaded with the key behavior.

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

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

The tool has a single required parameter and an output schema. The description covers the core behavior and parameter semantics completely. No additional details are needed given the output schema exists.

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 0% schema description coverage, the description fully compensates by specifying that 'username' requires an exact email. The schema only had a title 'Username', so the description adds essential 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 states a specific verb ('Force logout') and resource ('user by removing all their active sessions'). It clearly distinguishes from sibling tools like get_user_sessions (view only) or reset_password (different action).

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

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

The description implies admin usage ('Force logout') but does not explicitly state when to use this tool over alternatives like get_user_sessions or reset_password. No exclusion criteria or alternative suggestions are provided.

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

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

Covers the basic effect of resetting and temporary flag behavior, but lacks disclosure on required permissions, notification side effects, or logging. Without annotations, more behavioral context is expected.

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, front-loaded purpose, each sentence adds value. 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?

Adequately complete for a single-password reset tool; output schema exists so return value not needed. Could add usage scenario notes or prerequisites, but not essential.

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 for all three parameters: username is exact email, password is new password, temporary description explains forced change on login. Schema description coverage is 0%, so description fully compensates.

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 'Reset a user's password' with specific verb and resource. Distinguishes from sibling 'reset_passwords_batch' which operates on multiple users.

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?

Explains the 'temporary' parameter effect but does not provide guidance on when to use this tool versus alternatives like 'reset_passwords_batch' or other user management tools.

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

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

Without annotations, the description covers key behaviors: passwords not echoed, random generation, temporary flag effect. Missing error handling details, but overall good transparency.

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 yet informative, front-loads the purpose, and every line adds value. Structured with a clear Args section.

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

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

The description is complete for a batch tool with two parameters and an output schema. It covers input format, behavior, and edge cases without needing to duplicate output schema info.

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 explains both parameters well: csv_text format and temporary meaning. Despite 0% schema coverage, the Args section provides full 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?

The description clearly states it resets passwords for multiple users from CSV text, and it distinguishes itself from the sibling tool reset_password which handles single users.

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

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

The description gives detailed usage instructions including CSV format, password generation behavior, and the temporary flag. It contrasts with reset_password implicitly but lacks explicit 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?

No annotations provided. The description implies a read-only search operation with partial matching, but does not disclose any side effects, permissions, or response structure beyond the implicit search behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise and well-structured. Two sentences plus clear argument descriptions. Every detail 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?

Has an output schema, so return values need no further explanation. The description covers core functionality and parameters, but lacks usage guidelines or behavioral notes. Adequate for a 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?

Schema description coverage is 0%, so the description adds crucial meaning: 'query' is a partial match string, and 'max_results' has a default of 20. This fully compensates for the lack of 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 'Search users' and specifies the fields: username, email, first name, last name. It effectively distinguishes from siblings like 'get_user' (single user) and 'count_users'.

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

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

No explicit guidance on when to use this tool versus alternatives like 'get_user' or 'list_users_by_group'. It does not mention context or exclusions.

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

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

With no annotations, the description fully discloses behavior: blocking SSO logins, preserving custom attributes, not terminating existing sessions, and reporting remaining sessions. This is comprehensive and transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with a clear opening sentence, bulleted args, and no wasted words. It front-loads the key action and follows with important details.

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

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

Given the presence of an output schema and many sibling tools, the description is complete. It explains the tool's behavior, side effects, and relationship to logout_user, covering all necessary aspects 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?

Schema coverage is 0%, so the description must explain parameters. It describes 'username' as exact username (email) and 'enabled' as True/False. While this adds minimal value beyond the schema types, it is sufficient and contextually correct.

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 the tool enables or disables a user account, using a specific verb and resource. It distinguishes from siblings like logout_user by explaining that disabling blocks authentication but does not end existing sessions, making the purpose clear and unique.

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 when to use this tool (disabling a compromised or decommissioned account) and mentions an alternative (logout_user) for terminating existing sessions. This provides clear guidance on when to use versus other tools.

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

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

With no annotations provided, the description carries the full burden and does so exhaustively: it discloses the deadline/time-bounded behavior, the complete:false lower-bound semantics, confidence labeling rules, known-egress labeling (never excluded), resolve caps and shared-deadline stopping, and the invariant that breaches come only from actual LOGIN events.

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 purpose and interpretation guidance are front-loaded, but the block is very long and dense, with the return-shape enumeration and several repeated cautions (publish/lower-bound) that could be tightened. Detail is largely warranted given no output schema, but it is closer to a wall of text than a crisp definition.

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?

There is no output schema, so the description must explain returns, and it does so thoroughly (window, complete, spray, external_ips, breached_total, resolves_used, etc.), along with the KEYCLOAK env dependencies and interpretation rules. An agent has everything needed to call and read this tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate and largely does: all seven parameters are documented in the Args block with defaults and meaning (including the min_report_users clamping to min_users). One inconsistency weakens it: max_user_success_rate is documented as default 0.3 while the schema declares 0.2.

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

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

States a specific verb and resource ('Detect password-spray sources and name the accounts they breached') with a clear scope via the detection rule (unique_users >= min_users AND success_rate < max_success_rate). This distinguishes it from generic siblings like get_login_failures_by_ip and get_brute_force_status, which lack breach-naming and confidence semantics.

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

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

Gives strong operational context: read top_failed_users and not_found_domains before writing up, treat low-confidence successes as 'verify with the owner', and re-call with a narrower window rather than retrying. It never explicitly names which sibling to use instead, so the when-to-use-vs-alternative routing is implied rather than stated.

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