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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context by specifying the output concept (SIDs) and the integration purpose. It does not contradict annotations and adds value beyond them.

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

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

A single sentence with no filler. The READ tag and core purpose are front-loaded, and the downstream consumer (entitlement_add) is named efficiently without waste.

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

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

For a simple read-only search tool, the description plus annotations and full schema coverage are nearly complete. The description states the output goal (SIDs) even though no output schema exists. It could specify response shape or pagination behavior, but the current definition is adequate for correct selection and invocation.

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

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

Schema description coverage is 100%, so all three parameters (name, limit, target) are already documented. The description adds no extra parameter-level detail beyond the schema. Baseline 3 is appropriate because the schema carries the full burden.

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

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

The description states a specific verb ('Resolve'), a specific resource ('AD users/groups'), and a concrete outcome ('to their SIDs'). It also distinguishes itself from the sibling tools by tying its purpose to entitlement_add, so an agent can tell what this tool does at a glance.

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 contextual usage by explicitly saying this is needed to entitle a pool via entitlement_add. It does not list exclusions or alternatives, but there is no close sibling search tool to differentiate from, so the downstream pointer is sufficient.

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

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

The annotations already signal read-only and non-destructive behavior, so the burden is lower. The description adds a [READ] tag, explicitly states that the result is paginated, and lists the returned fields, providing useful behavior beyond the annotations without contradicting them.

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

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

The single sentence is front-loaded with the READ tag and has zero fluff. It packs the action, resource, fields, and pagination into a compact, unmistakable frame, and every word earns its place.

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

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

For a simple list tool with no output schema, the description covers the output fields, pagination, and read-only nature. The target parameter is left to the schema, which already defines it, so there is no substantive gap. It stops short of a 5 only because it does not mention the relation to separately paginated siblings or any optional filtering behavior, though these are not necessarily expected.

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 100% description coverage for all three params, so the baseline is 3. The description's mention of pagination selectively addresses limit/offset but adds nothing about the target parameter. No additional meaning is given that isn't already available in the schema, so a 3 is appropriate.

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

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

The description states a clear verb ("List") and resource ("published application pools") and enumerates the fields returned (id, name, farm, enabled, executable path). It is clear and concise, but it does not explicitly differentiate itself from the sibling pool_list, so it leaves a slight ambiguity for an agent deciding which list tool to use.

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 communicates what the tool does but not when to use it relative to alternatives. There is no mention of when to prefer this over pool_list, pool_get, or other sibling tools, and no mention of conditions like 'use this to list all published app pools' or exclusions. The purpose implies a use case, but the boundary is left to the agent to infer.

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?

It discloses behavior beyond annotations: a bare call returns blast_radius and grants nothing, confirm=True grants, the tool refuses when entitlements cannot be read, and it is audited. It also includes an important safety directive: do not set confirm=True on your own because the user has not yet seen the blast radius. No contradiction with the annotations is present.

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

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

The description is compact and front-loaded: the purpose appears in the first sentence, followed by essential workflow and safety guidance. Every sentence earns its place, including the final 'Audited.' There is no repetition of schema details or unnecessary elaboration.

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 explains the return behavior of a bare call (blast_radius with pool identity, existing vs new principals) and the effect of confirm=True. It covers the key prerequisites, the refusal edge case, and the required user interaction step. This is sufficient for an agent to select and invoke the 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?

The schema already covers all parameters at 100%, and the description adds meaningful context: ad_user_or_group_ids are SIDs from ad_user_search, pool_id comes from pool_list, and confirm=False/default returns blast_radius while confirm=True grants. The blast_radius explanation ('which principals are already entitled and which are new') adds value beyond the schema descriptions.

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

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

The description opens with a clear verb and resource: 'Grant desktop-pool access to AD user/group SID(s).' It also clarifies the write nature with '[WRITE]' and names the exact entity being modified, distinguishing it naturally from entitlement_remove. The scope is specific enough that an agent can understand what this tool does without inspecting 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?

The description gives strong usage workflow: get SIDs from ad_user_search, call without confirm to see blast_radius, show it to the user, wait for their decision, and do not auto-confirm. It also states a refusal condition. It stops short of explicitly naming alternatives such as entitlement_remove, but the 'Grant' phrasing and sibling list make the use case clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral details beyond those annotations: pagination and the teaching 404 on a wrong pool id, which helps the agent handle failures gracefully. No contradiction 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 short sentences carry all essential information: purpose, pagination, error behavior, and id-sourcing guidance. The most important scoping information is front-loaded, and no filler or repetition is present.

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

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

For a simple read-only paginated list tool with robust annotations and fully documented parameters, the description is complete. It covers what the tool returns (entitled AD users/groups), how pagination works, the failure mode on invalid ids, and where to get valid ids. No additional context is needed 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 description coverage is 100%, so the schema already documents all four parameters, including the default limit/offset and the target field. The description adds only minor value by connecting pool_id to pool_list, but this is already echoed in the schema; thus baseline 3 is appropriate.

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

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

The description states a specific verb ('List'), a concrete resource ('AD users/groups entitled to a desktop pool'), and an accessibility gloss ('who can access it'). The term 'List' plus the entitlement_set naming distinguishes it from sibling tools like entitlement_add and entitlement_remove, and the reference to pool_list differentiates it from that sibling.

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

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

The description gives clear context: it is paginated and requires a pool id, and it explicitly routes users to pool_list for obtaining valid ids. It does not explicitly state when not to use the tool or name alternatives for modifying entitlements, but the context is strong enough for an agent to use it correctly.

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

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

Beyond the annotations (destructiveHint, readOnlyHint:false), the description discloses the critical two-phase behavior, the no-op bare call, the refusal condition when entitlements cannot be read, and that calls are audited. This gives an agent the safety context it needs.

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

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

The description is well structured: it leads with the core action, then the two-phase workflow, refusal condition, and safety instruction. Every sentence contributes necessary information without filler.

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

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

For a destructive, two-phase tool with no output schema, the description is complete: it explains the blast_radius return, how to confirm, when it refuses, what inputs to use, and the required user-decision loop. Nothing necessary for correct and safe invocation 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 already 100%, and the description adds important semantics: ad_user_or_group_ids must come from entitlement_list, pool_id from pool_list, and confirm's default false versus true behavior is explicitly tied to blast_radius and revocation. The description adds meaning beyond the schema definitions.

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

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

States a specific verb and resource: 'Revoke desktop-pool access from AD user/group SID(s).' The two-phase behavior (bare call returns blast radius, confirm=True revokes) further clarifies exactly what the tool accomplishes, and the instruction to get SIDs from entitlement_list distinguishes it from sibling tools.

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

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

Gives clear context for safe use: show blast_radius to the user and wait for their decision, and never set confirm=True unilaterally. It also names the source tool for SIDs (entitlement_list), though it does not explicitly discuss alternatives such as entitlement_add for granting access.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds behavioral context: 'newest first', 'paginated', and the fields each item contains (time, severity, type, module, user, machine, message). This goes beyond annotations without contradicting them.

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

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

Two compact sentences. The purpose and scope are front-loaded, and the item-field list is a useful detail packed efficiently. No filler or repetition; every sentence adds value.

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

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

For a read-only, paginated list tool with fully documented parameters and no output schema, the description covers everything an agent needs: what it returns (item fields), ordering, filtering, and a use case. It is complete 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 description coverage is 100%, so all four parameters (limit, offset, target, severity) are already documented with types and defaults. The description only adds the notion of optional severity filtering, which is also in the schema. It provides no extra semantics beyond what the schema conveys, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List Horizon audit events') with clear scope (newest first, optional severity filter). The READ prefix reinforces read-only intent, and the use case ('what went wrong recently') makes it distinguishable from sibling tools like session_list or health_summary.

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 a clear use case: 'Use for "what went wrong recently"'. It does not explicitly name alternatives or exclusions, but the audit-event focus implicitly separates it from other list tools. The guidance is adequate for an agent to know when to invoke it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds useful context beyond those annotations by explicitly marking the operation as '[READ]' and revealing that results are paginated.

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

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

A single, front-loaded sentence communicates the operation kind, resource, returned fields, and pagination behavior with zero filler. Every element 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 paginated list operation, the description names the resource, the returned fields, and the pagination behavior. Parameters are fully covered by the schema, and annotations cover the safety profile. No output schema exists, but the stated field list is enough for the agent to 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 100%, so the parameters limit, offset, and target are already fully documented in the schema. The description adds only a general 'Paginated' signal and does not need to repeat parameter details; baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'List Horizon RDS farms' with exact returned fields (id, name, type, enabled, RDS server count). This clearly scopes the operation and distinguishes it from sibling list tools like image_list, pool_list, and machine_list.

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

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

The description implies this tool is for listing farms, but it does not explicitly state when to use it versus alternatives or when not to use it. Context is clear enough for a simple resource-list operation, but exclusionary guidance is absent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description need not repeat those. It adds behavioral context by stating it 'aggregates sessions, machines, and pools into a compact status,' which goes beyond the annotations. It also hints at the return content (session totals, problem machines, pool availability), though it does not detail format or pagination—acceptable given the read-only, idempotent nature.

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

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

Two sentences with zero waste. The core summary is front-loaded, and the drill-down guidance follows naturally. Every word contributes value.

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

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

For a read-only summary tool with no output schema, the description adequately covers what it returns and how to proceed. It mentions the aggregated categories and points to follow-up tools. It does not mention limits like time ranges or defaults beyond what the schema covers, but these are not critical for a health summary. Overall, it is sufficiently complete.

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

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

The single parameter 'target' is fully described in the schema ('Horizon target from config.yaml; omit to use the default.'), so schema coverage is 100%. The description adds no further parameter semantics, which is fine—the baseline of 3 applies because the schema does the heavy lifting.

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

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

The description states a clear purpose: 'One-glance Horizon VDI health: session totals by state, problem machines, pool availability.' It names the resource (Horizon VDI) and the aggregated content, and distinguishes itself from siblings by positioning as the 'first thing to call for how is VDI right now?' and pointing to drill-down tools like machine_list and session_list.

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

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

Explicitly tells when to use it ('first thing to call for how is VDI right now?') and when to use alternatives ('Drill into problems with machine_list --state or session_list'). This gives clear routing and avoids confusion with the many 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the behavioral context that this lists the golden-image catalog specifically for pool_push_image, which is useful. However, it doesn't disclose details like whether snapshots are returned hierarchically, whether base_vm_id filtering changes the shape, or pagination/limits. With annotations covering safety, a 3 is appropriate.

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

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

A single sentence that front-loads the action and resource, then adds the key contextual link to pool_push_image. Zero waste, and the [READ] prefix is a useful signal. 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 read-only list tool with 2 optional parameters, full schema coverage, and annotations covering safety, the description is nearly complete. The only minor gap is not describing the return shape (e.g., whether it returns both base VMs and snapshots in one list or separately), but with no output schema and a simple list operation, this is a minor omission.

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

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

Schema description coverage is 100%, so both parameters (target and base_vm_id) are already documented in the schema. The description adds the context that base_vm_id scopes snapshots to one base VM, which aligns with the schema. It doesn't add syntax or format details beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb ('List') and resource ('instant-clone base VMs and snapshots'), and explicitly frames it as the golden-image catalog for pool_push_image. This clearly distinguishes it from sibling tools like machine_list or pool_list, and the [READ] prefix reinforces the read-only nature.

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

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

The description implies when to use this tool: when you need the golden-image catalog for pool_push_image. It doesn't explicitly name alternatives or exclusions, but the reference to pool_push_image provides clear context for when this tool is relevant. Sibling tools like machine_list and pool_list are distinct enough that an agent can infer the appropriate choice.

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

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

The description goes beyond the readOnly/idempotent annotations by disclosing the 404 behavior on wrong ids, enumerating the return projection (id, name, pool_id, state, assigned user, agent_version, base_image), and clarifying that it uses a single GET rather than a list scan. This is valuable behavioral context not available from annotations alone.

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

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

The description is compact and front-loaded, with the core read action in the first sentenceair quotes and supporting context in the next two sentences. There is no fluff; every phrase contributes to selection, invocation, or error understanding.

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 single-fetch tool with two parameters nhỏ, the description covers purpose, when to use it, behavior on wrong ids, and the full return shape despite the lack of an output schema. The optional target parameter is fully documented in the input schema, so nothing essential 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 100%, and the schema already explains machine_id as an opaque id, not a display name or vCenter VM name, with the 404 hint. The main description doesn't add much beyond confirming the id comes from a machine_list row, so a baseline of 3 is appropriate.

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

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

The description opens with '[READ] One Horizon desktop machine by id', naming a specific verb, resource, and lookup method. It also distinguishes itself from machine_list by explicitly saying it fetches one row instead of scanning the estate, making sibling differentiation clear.

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

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

It gives explicit when-to-use guidance: 're-check one machine after a write, or when you already hold an id.' It also contrasts with machine_list by noting the same projection is fetched with a single GET 'instead of scanning the estate', and the schema's wrong-id hint tells the agent to re-run machine_list for exact ids.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value beyond that by mentioning pagination, the output fields (id, name, pool_id, state, etc.), and the filter behavior. It reinforces the read-only nature with '[READ]' and clarifies the state enumeration, which helps set expectations without contradicting any annotation.

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

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

The description is concise and front-loaded with the key purpose and read-only marker. It then lists the returned fields and a usage hint in a second paragraph, with no fluff. Every sentence adds value, and the structure aids quick scanning.

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 list operation with all optional parameters and no output schema, the description covers the essential aspects: what it lists, filters, pagination, output fields, and a usage context. The schema covers parameter details, so the description is complete for an agent to call the 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?

The schema provides 100% coverage with descriptions for all five parameters, so the description does not need to add much. It does confirm that filtering is by pool and state, which matches the schema, but does not introduce new semantic detail beyond what the parameter descriptions already offer. A baseline of 3 is appropriate.

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

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

The description states a clear verb ('List') and resource ('Horizon desktop machines'), specifies filters (pool id/state), and notes pagination. It distinguishes itself from sibling machine_get (single item) and write tools by explicitly labeling as a read operation with '[READ]' and the verification hint.

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 contextual guidance by noting 'Verify pair for the machine write tools', implying use before writes. However, it does not explicitly compare to machine_get or other list tools (e.g., pool_list), leaving some when-to-use/alternative distinctions to inference. Still, the purpose is clear enough for an agent to select it appropriately.

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

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

Beyond the annotations, it discloses the two-phase behavior, the exact contents of blast_radius, that a bare call changes nothing, that unreadable machines are refused, and that the operation is audited. This aligns with readOnlyHint=false and idempotentHint=true rather than contradicting them.

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

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

The first sentence front-loads the core action, and each following sentence carries essential operational or safety information. There is no filler or repetition; the length is appropriate for a two-phase mutation with significant safety implications.

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, the description does explain the blast_radius return value for the read-only first call, plus refusal and audit behavior. A minor gap remains: what the caller should expect after confirm=True applies is not described, and the fate of existing sessions is only implied by 'no new sessions.'

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the enabled and confirm semantics already present in the schema and adds a safety policy, but it does not materially expand parameter meanings beyond what the input schema documents.

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 pair: 'Enter (enabled=True) or exit (False) maintenance mode for machine(s).' It also clarifies the operational effect, 'Maintenance drains the machine (no new sessions),' which distinguishes this from sibling machine mutators like machine_reset or machine_remove.

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

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

It gives explicit procedural guidance: call without confirm to inspect blast_radius, show the user, wait for their decision, and never auto-confirm before the user has seen the blast radius. It does not explicitly list when-not-to-use or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, but the description adds critical behavioral context: the two-phase confirm flow, the blast_radius return payload, refusal when a machine state cannot be read, and the 'Audited' note. It also explicitly warns about the irreversible deletion of backing VMs for instant clones. This goes well beyond the annotations.

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

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

The description is compact and front-loaded: the destructive warning comes first, then the two-phase behavior, then the refusal condition, then the user-decision instruction. Every sentence earns its place, and the 'Audited' note is a useful one-word signal. 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?

For a destructive mutation tool with no output schema, the description is remarkably complete: it explains the return value (blast_radius), the confirmation flow, the refusal edge case, and the irreversible consequence. An agent has everything needed to call it safely and correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by explaining the confirm parameter's two-phase behavior (false returns blast radius, true removes) and clarifies machine_ids come from machine_list. It doesn't add much on target, but the schema already covers it. This is a solid enhancement over the schema.

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

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

The description opens with a specific verb and resource ('Remove machine(s) from their pool') and immediately distinguishes the destructive consequence for instant clones ('DELETES the backing VM'). It clearly separates from siblings like machine_reset and machine_maintenance by focusing on removal and deletion.

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 explicit when-to-use guidance: a bare call returns blast_radius and removes nothing; confirm=True removes. It instructs the agent to show blast_radius to the user and wait for their decision, and explicitly warns not to set confirm=True on its own even if the user asked earlier. This is strong, actionable usage guidance.

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

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

Annotations already mark this as destructive and non-read-only, but the description adds substantial context beyond that: the two-phase confirm behavior, the refusal to reset machines whose state cannot be read, the expectation to show blast_radius to the user, the warning not to self-confirm, and the 'Audited' note. This gives the agent a clear mental model of the tool's safety envelope.

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?

Every sentence earns its place: core operation first, then the two-phase workflow, then the user-consent warning, then the alternative tool. Densely informative with no filler or repetition of schema content, and the most safety-critical guidance is front-loaded.

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

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

The description fully equips an agent to call this tool correctly despite the absence of an output schema: it explains exactly what a bare call returns (blast_radius with machine ids, names, states, assigned users), how confirmation works, what can cause refusal, and when to route to a different tool. Nothing critical 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 100%, and the schema already explains confirm's false/true semantics, machine_ids source, and target default. The description reinforces the confirm behavior but does not add new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Hard-reset desktop machine(s)' and immediately states the consequence ('user loses unsaved state'). This clearly distinguishes it from siblings like machine_remove or machine_maintenance, and the explicit contrast with vmware-aiops further disambiguates it from graceful reboot operations.

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 explicit workflow instructions: a bare call returns blast_radius and resets nothing, confirm=True resets, and the agent must show blast_radius and wait for user decision before setting confirm. It also names an alternative tool for graceful reboots (vmware-aiops), making the when-to-use vs when-not-to-use boundary explicit.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds useful context beyond annotations: a wrong id returns 404, the response projection matches pool_list rows, and the operation is a single cheap GET. No contradiction with annotations.

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

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

Two sentences fully carry the purpose, projection, error behavior, and usage guidance with no filler. The [READ] tag and core statement are front-loaded, and the field list earns its place because there is no output 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?

For a simple getter with no output schema, the description covers what is returned, the error case, the usage decision, and relation to pool_list. The input schema fully documents both parameters, so nothing needed to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, and the schema already explains that pool_id is the opaque id from pool_list and that a wrong id returns a 404. The description adds little beyond 'by id' and 'already hold an id,' so the baseline 3 is appropriate.

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

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

The opening '[READ] One desktop pool by id' gives a specific verb, resource, and scope agenda. The note that it returns the same projection as a pool_list row distinguishes it from pool_list, machine_get, and session_get without requiring any of those schemas.

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

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

It gives explicit decision rules: use it to re-check a pool after a write, or when an id is already held. It also contrasts with the alternative by saying it uses a single GET instead of listing every pool, so an agent knows when not to call pool_list.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the [READ] prefix confirms safety. The description adds the type field enumeration and the paginated envelope note, which clarifies the return structure. It does not detail pagination behavior, but given the annotations cover the read-only nature, this is sufficient.

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

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

The description is two sentences with no waste. It front-loads the [READ] prefix and the verb 'List', then enumerates fields concisely. The second sentence adds a critical functional relationship and the pagination note in a compact way. Every word contributes.

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 three optional parameters and full schema coverage, the description is complete. It tells the agent what it returns, the type values, and its role in verification. The output schema is absent, but the field list compensates. Nothing missing 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?

The schema description coverage is 100%, so each parameter (limit, offset, target) is already documented in the schema. The description only adds the pagination envelope concept, which is minimal. The description does not add extra semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states it lists Horizon desktop pools and enumerates the fields returned (id, name, type, enabled, assignment). It also mentions the type values (AUTOMATED/MANUAL/RDS), which distinguishes it from app_pool_list and other list variants. The verb 'List' plus the resource and scope 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?

The description explicitly states it is the 'verify pair' for two sibling tools: pool_set_enabled and pool_push_image. This gives clear guidance on when to use this tool (to verify changes) and implicitly distinguishes it from other list tools. There is no direct alternative named, but the relationship to specific siblings is stated, which is more than typical.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds critical behavioral detail: every desktop is recreated, confirm=False is a no-op preview, confirm=True schedules the destructive action, occupancy can be 'determined' or 'unknown', and the operation is audited. No contradiction with the annotations.

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

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

The description is dense but every sentence earns its place: the destructive warning is front-loaded, the preview/confirm protocol is explicit, and the closing 'Audited.' adds useful context without padding. It is appropriately sized for a high-risk operation.

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 output schema, the description does a good job explaining preview fields, occupancy semantics, and the confirmation flow. It is slightly incomplete in that it does not state what confirm=True returns after scheduling, such as a task identifier or how the agent should monitor the resulting operation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by tying confirm and acknowledge_unknown_occupancy to the blast_radius occupancy states and the required user-decision protocol, which clarifies their real-world semantics. The remaining parameters are adequately explained 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?

The description states a specific verb and resource ('Apply the pending image to an instant-clone pool') and immediately escalates the risk with 'RECREATES EVERY DESKTOP' and 'Highest blast radius in the family.' This makes the tool's purpose and scope unmistakable and separates it from lower-impact pool or machine operations.

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 an explicit workflow: call with confirm=False to preview, show blast_radius to the user, wait for their decision, and only then set confirm=True. It also explicitly warns not to confirm autonomously because the user has not yet seen the blast radius, which is exactly the kind of when-not-to-use guidance an agent needs.

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

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

Beyond the annotations (readOnly=false, idempotent=true), the description discloses the confirmation workflow, idempotent noop behavior, refusal when current state cannot be read, and the audited nature of the call. This is exactly the behavioral context an agent needs for a mutation with side effects.

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 action and effect, and every subsequent sentence earns its place: idempotency, blast_radius workflow, refusal condition, and user-consent rule. It is information-dense without redundancy.

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

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

For a mutating tool with no output schema, the description covers the return contract (blast_radius contents), the confirmation semantics, the failure case (cannot read current state), and the safety requirement of user consent. This is complete enough for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents target, confirm, enabled, and pool_id. The description adds meaningful semantics for confirm (bare call returns blast_radius and changes nothing; True applies it), and clarifies the enabled effect, which goes slightly beyond the schema's one-line 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 opens with '[WRITE] Enable or disable a desktop pool' and clearly states the behavioral scope ('disabling stops NEW sessions (existing keep running)'). This distinguishes it from sibling pool_list/pool_get/pool_push_image and leaves no ambiguity about what the tool does.

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 explicit operational guidance: a bare call only returns blast_radius, confirm=True applies the change, and the agent must 'Show blast_radius to the user and wait for their decision.' It even states a when-not ('Do not set confirm=True on your own because the user asked for this earlier'), which is more actionable than a generic alternative comparison.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations: it states the output is sorted by utilization and specifies the exact metrics included. It also hints at a drill-down workflow. This provides useful behavioral detail without contradicting annotations.

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

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

The description is two sentences with zero fluff. The core purpose and metrics are front-loaded, followed by a use case and a drill-in pointer. Every word earns its place, making it highly concise and well-structured.

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

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

For a read-only tool with one optional parameter and no output schema, the description adequately conveys the return content (capacity metrics and utilization %) and provides a usage context. It does not cover potential error conditions or edge cases, but given the simplicity and annotations, this is sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100% for the single parameter 'target', which is well-described in the schema ('Horizon target from config.yaml; omit to use the default.'). The tool description does not add any parameter-specific information, but the schema already fully documents it. Baseline of 3 is appropriate.

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

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

The description states a specific verb ('Per-pool capacity') and resource ('pool'), lists the exact metrics (total/available/in-use/error machines and utilization %), and explicitly differentiates from sibling machine_list by suggesting drill-in. It clearly conveys what the tool returns and how it differs from related tools.

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

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

The description gives a clear use case ('am I running out of desktops?' view) and explicitly points to machine_list for drill-in, which helps an agent decide when to use this vs. a deeper dive. However, it does not explicitly contrast with other siblings like pool_list or health_summary, so it lacks full exclusion guidance.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description reveals important behaviors: state is preserved, reconnection is allowed, a bare call is non-destructive, sessions with unreadable users are refused, and the operation is audited. This contextualizes the destructiveness and gives the agent a safe interaction pattern.

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 dense but every sentence earns its place: the action and key behavior in the first line, the distinction from logoff, the safe-call workflow, the refusal edge case, and the user-consent directive. It is front-loaded with the essential purpose and safety guidance.

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 destructive tool without an output schema, the description covers everything an agent needs to invoke it correctly: how to identify targets, what the default call does, how to get consent, what happens on refusal, and auditability. The target parameter is documented in the schema, so no critical gap remains.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by clarifying the relationship between session_ids and user ('Identify by session_ids OR user') and by explaining the confirm parameter's effect (bare call vs. actual disconnect). This goes slightly beyond the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Disconnect Horizon session(s)'. It immediately distinguishes itself from the sibling 'logoff' by noting state is preserved and the user can reconnect, so an agent can tell it apart from session_logoff without opening that tool's definition.

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 contrasts with logoff ('Less disruptive than logoff') and details the safe usage workflow: a bare call returns blast_radius without side effects, the agent should show this to the user and wait, and confirm=True should only be set after user approval. This is actionable when-to-use guidance that prevents premature destructive action.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world traits. The description adds meaningful behavioral context beyond this: a wrong id returns a teaching error rather than a traceback, which helps the agent anticipate error behavior and recovery steps.

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

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

The description is compact and front-loaded: it states the operation in the first sentence, then adds the useful error-behavior and id-discovery guidance. Every sentence earns its place with no redundancy.

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

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

For a simple two-parameter read tool with a fully documented schema and no output schema, the description is complete: it explains what the tool returns conceptually, how to obtain a valid id, and what happens on failure. Nothing essential is missing 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 description coverage is 100%, so the schema already documents both session_id and target fully. The description reinforces that session_id comes from session_list but does not add meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific operation: retrieving full detail for one Horizon session by id. It distinguishes itself from sibling list tools by emphasizing 'one session' and 'full detail', and it points to session_list for id discovery, so an agent can tell this tool apart from nearby 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 explicitly tells the agent to use session_list to discover ids, which covers the key prerequisite and primary alternative. It also frames the tool as the correct choice when full detail for a single known session is needed, giving clear contextual guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive. Description adds the return envelope shape and field enumeration, plus pagination. It also states the READ nature upfront. That adds context beyond annotations, though it doesn't discuss any edge cases like empty results or errors.

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

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

Two sentences, front-loaded with [READ] and purpose, then compact return spec. No wasted words.

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

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

For a paginated list with rich output spec, the description is complete: it explains the envelope, item fields, and the verify use-case. Given annotations cover safety, nothing critical 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 covers all 6 parameters with descriptions (100% coverage). Description summarizes filters but doesn't add new meaning beyond what schema provides; baseline 3 is appropriate.

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

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

States a specific verb 'List' and resource 'Horizon VDI sessions', with explicit filters (user/pool/state) and pagination. Distinguishes from siblings by calling itself the 'verify pair' for logoff/disconnect, so the agent knows it's the listing tool for those actions.

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

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

Explicitly tells when to use it: 'This is the verify pair for logoff/disconnect — get a session id or confirm a user's sessions here first.' This gives clear context for when to invoke it, though it doesn't list alternatives or exclusions. Still, it's strong guidance.

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

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

Beyond the destructive/readOnly annotations, the description discloses the write-back trigger, the safe dry-run blast radius behavior, the refusal condition for unreadable users, and the audit trail. This is substantial behavioral context an agent needs before invoking a destructive 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 front-loaded with the core operation and side effect, then packs target selection, confirmation semantics, user-consent requirement, and audit status into a compact block. Every sentence earns its place with no redundant filler.

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

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

For a destructive tool with no output schema, the description is complete: it explains the safe default, what the blast radius contains, how to confirm, when a call is refused, and that the operation is audited. An agent has everything needed to invoke it correctly and safely.

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

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

Schema coverage is 100% and the parameter descriptions already cover substring matching, session_list origin, blast-radius behavior, and default target. The description adds little parameter-level meaning beyond reinforcing the session_ids-or-user choice, so the baseline 3 applies.

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

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

The description clearly identifies the action (force-logoff), the resource (Horizon sessions), and the side effect (kicks the user, triggers profile write-back), with target identification by session_ids or user. It doesn't explicitly name or contrast session_disconnect, but the 'force-logoff/write-back' framing is specific enough to avoid confusion with the disconnect sibling.

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

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

It gives explicit workflow guidance: bare call returns blast radius, confirm=True performs the logoff, show blast radius to user, and do not set confirm=True unilaterally. It doesn't explicitly state when to prefer this over session_disconnect or other siblings, so it stops short of a full when/when-not comparison.

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

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

Beyond annotations, the description adds meaningful behavioral context: "low blast radius", "informational only, no session disruption", "no confirm gate", and "Audited." These details are not inferable from readOnlyHint=false and destructiveHint=false alone.

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

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

The description is compact and front-loaded: the action, an example, risk level, targeting rule, and audit note all fit in three short sentences. Every sentence earns its place with no fluff or repetition of 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?

For a write operation with 100% schema coverage and no output schema, the description covers the important behavioral context: how to identify recipients, why confirmation is not needed, and why this is safe. It does not mention response behavior, but that is largely unnecessary for a message-sending tool and the schema already documents all parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value on top by clarifying the targeting relationship between session_ids and user, and reinforces the message text semantics with an example. This lifts it slightly above baseline.

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

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

The description begins with a specific verb+resource pattern: "Send a message to Horizon session(s)" and includes a concrete example message. It also distinguishes itself from disruptive sibling actions like session_logoff or session_disconnect by explicitly labeling this as informational-only.

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

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

It clearly states how to target sessions via "session_ids OR user", provides a realistic use case, and explains that no confirm gate is needed. It does not explicitly enumerate when not to use this tool versus alternatives like session_logoff, but the informational framing makes the intended usage clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered by structured data. The description adds the output nature (aggregate statistics) but does not disclose additional behavioral details such as data freshness, scoping semantics, or failure conditions, which is acceptable given the annotation coverage.

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

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

The description is two compact sentences with no filler. The [READ] marker and primary summary are front-loaded, and the sibling contrast is placed in the second sentence, making the essential information immediately visible.

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

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

For a read-only tool with one optional parameter and no output schema, the description adequately lists the return categories (concurrency by state/protocol, current concurrent, busiest pools). It does not specify the exact output structure, but the listed categories give an agent sufficient expectations for a straightforward stats call.

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

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

Schema description coverage is 100%, and the single optional target parameter is fully described with a default and usage guidance. The tool description adds no parameter-level detail, but the schema already carries that burden, so the baseline score of 3 applies.

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

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

The description states exactly what the tool provides: session statistics covering concurrency by state/protocol, current concurrent count, and busiest pools. It further distinguishes itself from session_list by clarifying it returns aggregate numbers, not per-session rows, making its purpose unmistakable.

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 names session_list as the reporting counterpart and contrasts aggregate numbers with per-session rows, giving an agent a clear decision point. It does not cover when to use other reporting siblings like pool_utilization or health_summary, so it is clear but not exhaustive.

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

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

Even with annotations marking destructiveHint=true, the description adds material behavioral context: bare call cancels nothing, confirm=True is required, unreadable tasks are refused, and already-applied work is not rolled back. The "Audited" note also signals operational oversight. This goes well beyond what the annotations alone convey.

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 action and then uses compact, purposeful sentences to explain the workflow, safety guardrails, and error conditions. Every sentence contributes value, and the formatting keeps the two-phase behavior easy to follow.

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 the critical return for a bare call (blast_radius with type, state, progress), the cancellation trigger, refusal conditions, and non-rollback. With no output schema, it could more explicitly state what confirm=True returns after cancellation, which is the main minor gap. Overall it is complete enough for safe invocation.

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

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

Schema description coverage is 100%, so the schema already explains all four parameters, including confirm's default/false behavior and target's default. The description reinforces confirm semantics but does not add new parameter-level meaning beyond what the schema provides. This meets the baseline but does not exceed it.

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

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

The description opens with a specific action and resource: "Cancel a running pool task" with an example (image push). It also clarifies the two-phase nature of the tool (read blast radius vs. actually cancel), which removes ambiguity about what a bare call does. Sibling tools like task_status or pool_push_image are clearly distinct from this cancellation operation.

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?

Explicit guidance covers when to use the bare call vs. confirm=True, and includes a firm when-not: "Do not set confirm=True on your own because the user asked for this earlier: they have not seen the blast radius yet." It also states the refusal condition when task type/state cannot be read, giving the agent concrete guardrails for invoking the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to cover safety. It adds valuable behavioral context: tasks are pool-scoped, and the tool supports two modes (single task vs. all tasks). It also reinforces the read-only nature with '[READ]'. No contradictions with annotations.

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

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

The description is a compact three-sentence block, front-loaded with '[READ]' to immediately signal it's a read operation. Every sentence adds value: the scope, the parameter usage, and the source of task_id. No filler or repetition.

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

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

For a read-only status tool with no output schema, the description provides essential context: what kind of tasks (long tasks like image push/provisioning), how tasks are scoped, and how to select between single vs. all tasks. It doesn't describe the return format, but that's often acceptable for status tools, and the tool name implies a status response. Overall, an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema: it specifies that task_id should come from pool_push_image or a prior task_status, and clarifies the omit-to-list-all behavior (already in schema but reinforced). It doesn't add detail for target or pool_id beyond what the schema provides, but the added task_id context is useful.

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 status of a pool's long task (image push/provisioning) or all tasks for the pool. It uses a specific verb ('Status') and resource ('pool's long task'), and distinguishes itself from siblings like task_cancel by focusing on reading rather than modifying tasks. The pool-scoping detail further clarifies its purpose.

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 explicit guidance on when to include task_id vs. omit it, and even mentions the source of a valid task_id (from pool_push_image or a prior task_status). It implies that for creating tasks you use pool_push_image and for canceling you use task_cancel, though it doesn't name these alternatives directly. It's clear when to use this tool, but doesn't state explicit exclusions.

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