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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds behavior beyond that: it mutates only the requested rules/bindings and leaves unrelated scope untouched, and it mandates readback plus unrelated-scope checks after applying. That is meaningful operational detail not present in 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?

Two tight sentences with the key scope constraint front-loaded before the mandatory-verification note. Dense but every clause carries meaning; minor jargon ('preflight', 'readback') without much 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 destructive tool with a large nested schema, no output schema, and a dry_run parameter, the description leaves too much unexplained: what the response contains, how failures/partial application are reported, and what dry_run actually returns. The preflight/readback notes help but do not fill the 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?

Schema description coverage is 0% across 5 params including a deeply nested Acl object, so the description must compensate. It only hints at the name-vs-number dichotomy ('numbered or named ACL') and at the rules/bindings structure; project_path, topology, device, acl_type, implicit_deny, and dry_run are entirely unaddressed.

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 ('Apply one strict Comware numbered or named ACL') and scopes it to a single ACL, which distinguishes it from hcl_remove_acl and the other hcl_apply_* siblings by domain. It stops short of naming a sibling outright, so it is clear but not maximally differentiating.

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?

'after identity, backup and restore preflight' implies a prerequisite ordering (use hcl_backup_config / identity checks first), which is real usage context. However, it never states when to prefer this over a plan/deploy path or what to do for removal, and it omits any mention of the available dry_run escape hatch.

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

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

The description adds meaningful behavioral context beyond annotations: it mentions scoped readback, saved recovery, unavailable serial clock and IOS delay mappings, partial encrypted authentication values, and omission of secrets from operation receipts and previews. These limitations and safety notes are substantive and consistent with the destructive 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 short and front-loaded with the core action. The second and third sentences efficiently convey important limitations, though some phrases such as 'scoped readback' are slightly cryptic.

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?

This is a destructive mutation tool with a nested parameter object, no output schema, and zero schema description coverage, so the description carries substantial burden. It covers key limitations and secret handling, but it does not provide enough operational detail about prerequisites, recovery behavior, or the full parameter set.

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 identify bandwidth, OSPF fields, and limitations around clock rate, delay, and encrypted authentication, but it does not explain most parameters such as router, interface, project_path, topology, dry_run, operation_key, timeout_seconds, or the OSPF interval fields.

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

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

The description names a specific verb and resource: 'Tune requested interface bandwidth and OSPF fields'. It is clear what the tool changes, but it does not explicitly distinguish this tool from nearby apply_* siblings such as hcl_apply_vlan or hcl_apply_acl.

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

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

There is no explicit guidance on when to use this tool, when not to use it, or which sibling alternatives are appropriate. The phrase 'requested interface bandwidth' implies a target, but no prerequisites or decision criteria are stated.

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

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

Annotations already flag destructive=true, idempotent=false, and closed-world, so the description is not carrying the whole safety burden. It still adds real value by disclosing bounded backup/readback/persistence and same-VM recovery — behavior an agent cannot infer from the annotations. It omits whether failure rolls back automatically and what the response contains, which is why it is not a 5.

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

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

Three tight sentences, front-loaded with the core action and scope before the operational caveats. No filler; the final sentence is dense but earns its place as a correctness warning. Slightly telegraphic phrasing ('same-VM recovery') costs a little readability.

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, non-idempotent mutation with a deep nested schema, no output schema, and near-zero parameter documentation, the description explains the transactional safety net but leaves too much open: dry_run semantics, the idempotency/operation_key contract, timeout behavior, and return payload are all unstated.

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% against a nested parameters object with roughly twenty properties, so the description must compensate and largely does not. It touches mode and obliquely alludes to acl_namespace and pool_netmask in the Comware/IOS sentence, but dry_run, operation_key, timeout_seconds, use_interface_overload, pool_address_group, and the inside/outside interface constraints get no explanation.

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 (apply) and resource (NAT intent) with explicit modes (static, dynamic, interface/pool PAT) and a scope boundary (one staged router). It implicitly separates from hcl_remove_nat and hcl_apply_acl, but never names an alternative, so it stops short of a 5.

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?

"One staged router" implies the device must already be staged and that this operates on a single target, which is useful selection context. However there is no explicit when-to-use versus hcl_remove_nat / hcl_apply_acl, no stated prerequisites (must the ACL/pool already exist?), and no guidance on when dry_run should be chosen.

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, idempotentHint=false, and openWorldHint=false, so the mutation profile is known. The description adds genuinely new context: named monitor/object equivalence and actual collector delivery remain unverified, warning the agent that success does not guarantee traffic reaches the collector. It doesn't cover the dry_run escape hatch or rollback 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?

Two tight sentences with the action front-loaded and the caveat second; nothing is redundant.

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, non-idempotent tool with a deeply nested request object, zero schema description coverage, and no output schema, the description says nothing about the dry_run/remove interplay, operation_key idempotency, or what a successful apply returns. The verification caveat is good but far from sufficient.

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

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

Schema description coverage is 0% and there is a nested NetstreamRequest with ~11 fields (device, name, remove, version, monitors, udp_port, interfaces, source_port, operation_key, destination_ip, timeout_seconds). The description only hints that 'name' is the local exporter identity; dry_run, remove, operation_key, and interface bindings are left entirely to the raw 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-pair (apply/remove) and resource (scoped NetStream destination), plus a scoping qualifier (local exporter-name identity). It is distinguishable from siblings like hcl_apply_nat or hcl_apply_acl by domain object, though it doesn't name an alternative explicitly.

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 statement of when to use this versus the other apply_* tools, no prerequisites, and no mention of how the remove mode trades off against a separate removal tool. Usage is only implied by the verb.

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, so the description's real contribution is the refusal semantics: the tool rejects unproved protect/restrict mappings and unrequested auth or sticky/learned-state conversion. That is useful pre-call context an agent cannot derive from the annotations. It still omits what dry_run does and that operation_key enables safe retries on a non-idempotent mutation.

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

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

Two short sentences with the capability stated first and the refusal constraint second — nothing is wasted. The phrasing is dense jargon ('bounded secure-MAC/shutdown intent', 'unproved IOS protect/restrict mappings') that takes a re-read.

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?

This is a destructive, non-idempotent mutation with a nested request object, 0% schema coverage, and no output schema, so the description should carry the load. Critical items are missing: dry_run's effect, operation_key's retry-safety role, timeout semantics, and what a successful apply returns or changes.

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 nested PortSecurityRequest carries eight properties, so the description must compensate and largely does not. 'Secure-MAC' vaguely gestures at max_mac/sticky/static_macs and 'shutdown' at the violation enum, but dry_run, operation_key, and timeout_seconds are unexplained in both schema and description.

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

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

States a specific verb ('apply') and a concrete resource ('bounded secure-MAC/shutdown intent on one existing access port'), including scope (one port, must already exist). A sibling set full of hcl_apply_* tools makes the naming pattern do some differentiation work, but the description itself never names an alternative, so it stops short of 5.

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?

'On one existing access port' implies a prerequisite, and the refusal clause tells the agent which requests will be rejected (unproved IOS protect/restrict mappings, auth or learned-state conversion). However, it never says when to prefer a sibling such as hcl_inspect_ports or hcl_audit_security first, and gives no guidance on when to use dry_run — usage is implied rather than stated.

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

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

Annotations already declare this as destructive, non-idempotent, and not read-only, so the safety profile is partly covered. The description adds scoped context about per-VLAN STP and unsupported equivalence claims, but it does not explain what configuration is changed, whether dry_run is recommended, or what operational risk 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 short and front-loaded, with the main action stated first. The second sentence is a useful caveat, though it is somewhat abstract and does not compensate for the missing parameter 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?

This is a destructive, nested-parameter mutation tool with no output schema and 0% schema description coverage. The description identifies the STP domain but is far too thin to fully prepare an agent for required inputs, dry-run behavior, or side effects.

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 carry parameter meaning. It alludes to priority and edge/guard intent, but does not explain required fields like topology, project_path, switch, mode, operation_key, dry_run, or timeout_seconds, leaving most nested parameters undocumented.

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: applying per-VLAN rapid spanning-tree priority and edge/guard intent. It is clearly a configuration-apply tool, though it does not explicitly distinguish itself from other hcl_apply_* siblings such as ACL, VLAN, or port-security 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 no explicit when-to-use guidance, no prerequisites, and no comparison to alternatives like hcl_validate_plan or hcl_generate_configs. The caveat about not being full IOS equivalence is a limitation, not 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 declare destructiveHint=true and idempotentHint=false, so the bar is lower, yet the description still adds real value: it discloses the backup/readback/recovery lifecycle and the non-obvious semantics that native trunk membership is REPLACED with the exact allowed VLAN set, which an agent would otherwise not know. It does not explain what backup/readback produce or what 'recovery' triggers, but the core destructive semantic is surfaced.

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, front-loaded with purpose and followed by the one non-obvious behavioral rule. No filler, though the trailing newline and slightly telegraphic style leave room for a tighter single statement.

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, non-idempotent write tool with a nested schema, no output schema and no parameter docs, the description covers the safety posture and trunk replacement but omits prerequisites (project/topology/device resolution), what backup/readback/recovery concretely do, and the effect of dry_run. Minimum viable but with clear gaps.

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

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

Schema description coverage is 0% across five parameters with deeply nested objects (vlans, names, ports, svis, native_vlan, allowed_vlans), so the description must carry the load. It only clarifies one semantic (native trunk membership is replaced by allowed_vlans); it says nothing about dry_run behavior, topology/project_path/device expectations, or how ports/svis/names interact. Large gap for a 0%-coverage 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 (apply) and resource (VLAN/port/SVI intent) and scopes it to a single device, which separates it from the network-wide sibling hcl_apply_vlan_network. It also names the safety rails (backup, readback, recovery) so the agent knows this is a staged, reversible-ish operation rather than a raw push.

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 word 'strict' and 'single-device' imply this is the per-device enforcement path versus the network-wide apply, but usage is only implied. There is no explicit when-to-use/when-not, no mention of preconditions (project must be open, topology/device must exist), and no pointer to hcl_apply_vlan_network or hcl_validate_plan as the alternative.

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, idempotentHint=false and non-read-only, so the safety profile is covered. The description adds that targets and backups precede changes, which is genuinely non-obvious sequencing context, but the closing clause about 'persistence and recovery stay bound to each VM' is too vague to act on and dry_run behavior is never explained.

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

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

Two short sentences with the core action front-loaded, which is good. The second sentence is cryptic and dilutes rather than adds ('bound to each VM' has no clear operational meaning), so space is spent without earning clarity.

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?

This is a destructive, non-idempotent mutation with nested objects, zero schema descriptions and no output schema — the highest-burden case. The description omits failure semantics, whether changes are transactional/rolled back, what backups are taken and where, and how dry_run differs, leaving the agent without what it needs to invoke 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 description coverage is 0%, so the description carries the burden — yet it explains none of the four parameters. The words 'VLAN/access/trunk/router subinterface' loosely map to the vlans/access_ports/trunks/subinterfaces arrays, but dry_run, topology and project_path are entirely unaddressed, and nested objects (Trunk, AccessPort, RoutedVlan) get no 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?

Names a specific verb (apply) and concrete resources (VLAN/access/trunk/router subinterface) plus the scope (staged devices). It does not, however, distinguish itself from the sibling hcl_apply_vlan, which by name appears to overlap heavily — the agent cannot tell which one to pick from the description 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?

'Across staged devices' hints that devices must be staged first, but there is no explicit when-to-use, when-not-to-use, or alternative named. The obvious sibling hcl_apply_vlan (and hcl_apply_acl/hcl_apply_nat) is never mentioned, and the available dry_run path is never recommended as a pre-check.

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 read-only, idempotent, non-destructive, closed-world behavior, so the description correctly focuses on what annotations cannot convey: credentials are not exported, an empty device falls back to staged non-PC bindings rather than a full native inventory, and Cisco rules / unknown storage algorithms block a secure=true verdict. This is substantive operating context beyond the structured fields.

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

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

Three short lines, purpose front-loaded, with no filler sentences. Some phrasing is compressed to the point of being cryptic, but nothing is redundant.

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 zero schema descriptions for four parameters, the description should explain the required project_path/topology inputs and what an audit result (secure verdict plus findings) looks like. It hints at the verdict logic but leaves the majority of the calling contract undocumented.

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% across 4 parameters, so the description carries the full burden. It only partially clarifies 'device' (empty selects staged non-PC bindings); 'topology', 'project_path', and 'timeout_seconds' are entirely unexplained in both schema and description, leaving required parameters without 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?

It names a specific verb ('Audit') and resource ('running Comware configuration posture'), but the wording is jargon-heavy ('bound', 'posture') and never plainly states what the audit produces. It is distinguishable from hcl_health_check or hcl_verify_connectivity only by inference, not by an explicit statement of scope.

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

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

The second sentence describes behavior when 'device' is empty, which is closer to semantics than usage guidance. There is no statement of when to prefer this over the many sibling audit/inspection tools (hcl_validate_plan, hcl_health_check, hcl_parity_report), and no prerequisites are given.

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 establish read-only, non-destructive, idempotent, and non-open-world behavior, so the description's added details are supplemental. It usefully clarifies that the tool never opens a socket and that its data comes from HCL's own logs rather than vendor documentation, which adds meaningful 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 only three short sentences and front-loads the core purpose. Every sentence adds value: the first states what is listed, the second states safety/offline behavior, and the third states data provenance.

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 the description need not explain return values, and the annotations cover the safety profile. The description is nearly complete for a zero-parameter read-only capability-listing tool, though it could be stronger if it explicitly distinguished this tool from similarly named 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?

The tool takes zero parameters, so there are no parameter semantics for the description to explain. The baseline for a parameterless tool is 4, and the description does not create any parameter-related confusion.

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

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

The description uses a specific verb and resource: it lists observed backend verbs with their evidence level and gating state. That is clear enough to distinguish the tool's basic function, but it does not explicitly differentiate it from sibling tools such as hcl_capabilities or hcl_backend_topology.

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 useful context for when this tool is appropriate: it is read-only and offline, and it reports observed backend verbs from HCL logs rather than vendor documentation. It does not name an alternative or explicitly say when not to use it, but the source/provenance distinction provides clear 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 declare the non-readOnly, non-idempotent, non-destructive profile, so the description correctly spends its words elsewhere: connection-keyed session lifetime, singleton session limit, and the project-root sandbox on working_directory. It does not say whether `close` tears down topology state or just releases the connection, which is the one behavior an agent most needs before closing.

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?

Short, front-loaded, and the most decision-relevant facts (state-changing, singleton, open prerequisites) come first. Minor noise from markup artifacts (double backticks, bold markers) and a stray paragraph break mid-thought.

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 values need not be described, and the session lifecycle and its coupling to hcl_device_power are covered. The remaining gap is the meaning of `udp_port` and `project_name`, plus how working_directory is resolved against a project root.

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 only partly does: it explains the `action` enum and the `topology`/`working_directory` pair required by `open`. `udp_port` (default 10000) and `project_name` are never mentioned, leaving two of five parameters opaque and their relationship to working_directory unclear.

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 set (open/inspect/close) on a specific resource (backend topology session), and explicitly flags it as state-changing. It also distinguishes itself from the crop of stateless siblings by naming hcl_device_power as the consumer of the session.

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 preconditions for the `open` path (needs `topology` and a `working_directory` inside a configured project root) and a hard constraint that only one session can exist at a time. It stops short of saying when to call `status` versus `close`, or what happens if you call open twice.

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

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

Annotations declare a write (readOnlyHint=false) and non-idempotent operation, and the description is consistent with that ('Create'). It adds useful context that it both creates and tests the backup and that a gate applies, but never explains what the gate checks or what happens on failure. Modest value beyond annotations.

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

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

A single front-loaded sentence with no filler. The parenthetical '(gated)' is slightly cryptic but efficiently signals a precondition.

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 non-idempotent write tool with no output schema and 0% parameter coverage, the description is thin. It doesn't clarify the gate, what 'bound staged device' means, or what the backup/test produces, leaving significant gaps 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 0%, and all three required parameters (project_path, topology, device) go undocumented. The description only hints that 'device' must be staged/bound, leaving the format and meaning of project_path and topology entirely unexplained.

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 concrete verb and resource: create and test a native running-config backup for a device. An agent can distinguish it from hcl_restore_config (the inverse operation). However, 'bound staged device' and '(gated)' are cryptic qualifiers that aren't explained, weakening the distinction.

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

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

There is no explicit when-to-use guidance, no mention of alternatives like hcl_restore_config or hcl_live_deploy, and no prerequisites for the 'gate' are given. The '(gated)' note hints at a precondition but leaves the agent to infer 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 readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds one genuinely new behavioral rule — that results must not be read as proof of GUI/CLI control — but says nothing about latency, failure modes, or what a failed probe implies.

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 compact sentence with the action front-loaded and no filler. The trailing caveat is slightly cryptic in phrasing but it is not padding.

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 is present, so return values need not be explained. However, for a tool whose whole job is reporting backend status, the description leaves the notion of "status" undefined and gives no operational context for interpreting a probe result beyond the one caveat.

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?

Zero parameters and a fully empty schema mean there is nothing for the description to disambiguate. The baseline for a no-argument tool applies, with no parameter-level gap to compensate for.

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?

It names a verb ("probe") and resource ("local HCL backend"), so the general action is clear. But "status" is never unpacked, and among siblings like hcl_backend_capabilities, hcl_backend_topology and hcl_health_check the agent cannot tell what distinguishes this probe from those.

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 only guidance is a negative caveat ("never infer GUI or CLI control from it"), which is not a when-to-use rule. Nothing says when to call this versus hcl_backend_capabilities, hcl_health_check, or hcl_verify_connectivity, which occupy adjacent ground.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered structurally. The description hints at a notion of an 'activation boundary' (a gating concept worth knowing) but never explains what that boundary means or how the result is shaped, leaving behavioral context thin.

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 short sentence, front-loaded with the verb, with no filler. It is efficient, though its brevity contributes to the vagueness rather than resolving it.

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 structural side is simple (no params, output schema present, annotations complete), so the description only needs to orient the agent. It fails to do so fully because 'activation boundary' is unexplained jargon and the tool's relationship to hcl_backend_capabilities is unstated.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool 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 verb 'Describe' is specific, but the resource is vague: 'verified capabilities' and 'the activation boundary' do not say capabilities of what, and the sibling hcl_backend_capabilities sounds like it covers a near-identical concern. An agent cannot confidently tell the two apart from the text 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?

There is no statement of when to call this tool, when not to, or which sibling to prefer. The presence of hcl_backend_capabilities and hcl_bridge_status makes the missing routing guidance a real gap.

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 the safety profile (destructiveHint=true, idempotentHint=false, openWorldHint=false), yet the description adds real substance: it executes exactly one line, it is gated, and pre-existing console output is drained and returned separately as discarded_stale_bytes so stale text cannot be misread as the response. That stale-output disclosure is precisely the kind of behavior an annotation cannot express.

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 core action is front-loaded in sentence one, followed by endpoint selection and then the stale-byte caveat, in roughly 65 words with no filler. The unexplained '(gated)' parenthetical and the dense final sentence cost it a point.

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 values need not be spelled out, and the destructive annotation covers the risk profile. But for an agent that will push arbitrary console lines to live devices, the definition omits what '(gated)' requires, what 'expect' does (timeout on a regex, presumably), and what happens on failure or timeout — key gaps given the schema is otherwise silent.

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 carry the parameter burden and it only partially does: it documents pipe with concrete formats (`\\.\pipe\<topology>-device<N>` and `telnet://127.0.0.1:<30001..31024>`) and the topology+device pairing with its default endpoint. Two of five parameters are left unspecified — 'expect' is never mentioned anywhere and its semantics are undetectable, and 'command' is only implied by the tool name.

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 names a specific verb and resource — send one line to a device console — plus the transport (HCL's telnet bridge), and the scope limit 'one line' is genuinely distinguishing. It never names a sibling (e.g. hcl_bridge_status for checking bridge health without executing), so it falls short of full sibling differentiation.

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

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

It specifies how to choose between two invocation modes (pipe alone, or topology + device), which is a form of usage guidance, but it never states when to use this tool rather than hcl_verify_connectivity, hcl_bridge_status, or a config-generation tool. The lone hint is the unexplained '(gated)' marker, which implies a precondition without saying what it is.

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

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

Annotations only declare the safety profile (write, destructive, non-idempotent, closed-world); the description adds substantial non-structured context: the session-gating model, the specific error code returned without a session, and that power-off is deliberately unimplemented rather than guessed. It does not describe side effects on the device state or what the response contains, but the output schema covers returns.

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 action and the gating caveat, then the two behavioral constraints. Compact and free of filler, though the reStructuredText backtick markup adds noise without 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 two-parameter mutation with annotations and an output schema, the key unknowns an agent needs — the session prerequisite, the failure code, and the unsupported power-off path — are all present. The remaining gap is how to source a valid device id.

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 carry parameter meaning. It meaningfully explains 'on' (default true, False unsupported) but says nothing about 'device' — notably that it is an integer identifier presumably obtained from hcl_list_devices, which is the one thing an agent most 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 and resource: power on exactly one device via an observed backend verb. The '(gated)' qualifier signals a precondition rather than the operation itself. No sibling in the list offers device power control, so differentiation is implicit via the resource, but the description never explicitly contrasts with the stage_*/apply_* live-mutation family.

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 the prerequisite — an open session from hcl_backend_topology — and names the concrete failure mode (errorCode=228) for one-shot calls. It also tells the agent that on=False is unsupported and should not be attempted. It does not, however, say when to prefer this over plan/stage tools or when a live power action is appropriate.

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/destructiveHint:false, so the bar is lower and the warning that some results "remain unknown until an authoritative native topology inventory is available" is a genuine addition about output trustworthiness. However, that caveat is phrased in vocabulary (guest observations, live devices, in_sync) that maps to nothing in the schema, so its behavioural value is hard to apply.

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

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

Two short sentences with no filler, and the compare action leads. But the second sentence is opaque jargon that consumes attention without conveying actionable information, so brevity here is not the same as efficiency.

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 a 60+-definition nested schema, no output schema, and no documented parameters, the description should explain what the diff returns (in_sync? missing/extra? per-device?) and how `topology` relates to `plan`. It covers none of that and uses unrelated vocabulary, leaving the agent unable to call this confidently.

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% across four parameters, including a deeply nested TopologyPlan and an opaque `topology` string. The description names none of them and gives no hint about what `topology` accepts (a path? a YAML/JSON blob? a backend handle?) or how `plan` is compared against 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?

"Compare" is a verb, but the objects are "planned addresses" and "freshly bound guest observations" – neither of which matches the actual inputs (project_path, topology, plan). The description never says it diffs a plan against a project's HCL state, so an agent cannot tell this apart from hcl_validate_plan, hcl_explain_plan, or hcl_parity_report.

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 statement of when to use this versus hcl_validate_plan or hcl_parity_report, and no prerequisites for project_path or the topology string. The second sentence only fences off a limitation; it does not route the agent anywhere.

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, so the safety profile is covered. The description contributes only the marginal fact that output involves counts of devices/links/addresses/services; it says nothing about determinism, error behavior, or relationship to a prior planning call implied by "the same planner".

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?

It is a single short sentence with no filler, so it is compact and front-loaded. However, the brevity comes from omission rather than efficiency — the sentence is too thin for what the tool needs to convey.

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 taking a large nested topology request (templates, VLANs, routing, wireless settings, PC/laptop distributions) with no output schema and no parameter descriptions, a one-sentence description is wholly inadequate. An agent has no basis to construct a valid request or interpret the 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?

There is one required top-level `request` object wrapping ~30 nested fields, and schema description coverage is 0% (only two nested fields carry any schema text). The description provides no parameter guidance whatsoever, leaving the entire large request shape undocumented.

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 phrase "count devices, links, addresses and services" hints at an output, but "Use the same planner" references something never identified, and the description never states what the tool actually consumes or produces as a plan estimate. Against siblings like hcl_plan_topology, hcl_validate_plan, and hcl_explain_plan, an agent cannot tell which one to pick from this text 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?

No when-to-use condition, no prerequisites, and no named alternatives. "Use the same planner" is a dangling reference that gives no selection criterion relative to the many planning-related siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds one genuinely useful trait, "without an LLM" (deterministic, non-model-generated explanation) and hints that output reports limits on what can be proven. It does not say what happens on an invalid plan or what the explanation contains.

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

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

One short sentence with no filler; the key qualifier ("without an LLM") is placed where it is visible. Only the cloudy phrase "evidence boundaries" costs a point.

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 a deeply nested ~50-definition input schema and no output schema, the description says nothing about the return value's shape or how the explanation is structured, which is the main thing an agent needs to decide whether to call it. The burden left by absent output schema is unmet.

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

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

There is a single parameter with 0% schema description coverage and a large nested TopologyPlan structure, so the description carries the full explanatory burden and provides none. It calls the input a "saved plan" while the schema takes a full plan object, not a saved-plan reference, which is ambiguous. No mention of required fields, schema_version, or size constraints.

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?

"Explain a valid saved plan" names a verb and resource, but "explain" is vague about what the output actually contains, and "evidence boundaries" is unexplained jargon. It does not distinguish itself from nearby siblings like hcl_validate_plan, hcl_estimate_plan, or hcl_fix_plan, all of which also consume a plan and produce analysis.

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

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

There is no when-to-use guidance: nothing says to explain rather than validate, estimate, or fix a plan, nor what condition makes a plan "valid" enough to explain. The reader must infer the tool's role in the workflow from its name alone.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description usefully adds 'atomically', telling the agent the export is all-or-nothing. However, it does not say whether an existing artifact with the same name is overwritten, what files are produced, or how the non-idempotent flag (idempotentHint=false) should be handled despite an idempotency_key parameter existing.

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

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

A single front-loaded sentence with no filler, and the atomicity/scope clauses come early. It is efficient, though the brevity leaves no room for the operational context this tool needs.

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

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

No output schema exists, so the description must carry the return story, and it partly does: it names the bundle contents (plan/config/operation) and the destination root. Still missing is what is actually returned (paths, listing, checksum), whether an existing artifact is replaced, and whether the plan must be pre-validated.

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% with three parameters, including a large nested topology plan object; the description only vaguely gestures at 'plan' and 'output root'. The idempotency_key parameter is never mentioned, and nothing clarifies what artifact_name controls (directory name? file stem? format?).

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?

It states a specific verb ('export') and a concrete artifact ('offline plan/config/operation bundle') with a scoping location ('under the output root'). It does not differentiate itself from nearby siblings such as hcl_generate_configs, hcl_generate_operations, or hcl_save_project, so an agent cannot tell without opening schemas whether this writes files or produces a combined package.

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

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

There is no when-to-use guidance, no mention of prerequisites (does a plan need to be validated or staged first?), and no named alternative. The word 'offline' hints at the boundary versus live deployment tools, but the agent must infer it.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful behavioral context: it returns a copy rather than mutating the input, and it preserves manually supplied addresses and services. It does not explain the repair scope, failure modes, or what other parts of the plan may be changed.

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

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

The description is a single front-loaded sentence with no wasted wording: it states the outcome and the preservation behavior immediately. It is concise and well-structured, though its brevity contributes to the gaps in other dimensions.

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 a complex topology-plan schema, no parameter descriptions, no output schema, and numerous sibling tools, the description is significantly under-specified. It does not explain what repair means, what the returned copy contains, or when this tool is the right choice. Annotations cover safety but not operational 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?

Schema description coverage is 0%, and the single parameter is a large nested TopologyPlan object. The description only hints that the plan contains manually supplied addresses and services, without explaining the plan structure, required contents, or how the repair uses those fields. The schema's titles and constraints help, but the description does not compensate for the missing parameter documentation.

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

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

The description states that it returns a repaired copy of a plan and preserves manually supplied addresses and services. However, it never defines what 'repaired' means, what defects are fixed, or how the result differs from sibling tools like hcl_validate_plan or hcl_plan_topology. The purpose is only vaguely identifiable from the name and wording.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as hcl_validate_plan, hcl_plan_topology, hcl_explain_plan, or hcl_stage_copy. Usage is only implied by the tool name and the phrase 'repaired copy'. No prerequisites, exclusions, or alternative-selection criteria 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?

Annotations already declare readOnly=false, destructive=false, idempotent=false, so safety basics are covered; the description still adds real substance: the activate default, that no VM power or CLI deployment happens, and the offline-vs-live replay distinction. There is some tension between "offline builds support durable idempotency" and idempotentHint=false, though the following clause ("live activation is never replayed") largely reconciles it. It never says whether an existing project at project_path is overwritten or what "open in an existing GUI" requires.

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?

Short and front-loaded: the verb-and-resource statement comes first, then the behavioral caveats. The second paragraph is a bit staccato ("activate defaults false" is a fragment) and is not clearly ordered, but no sentence is 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 tool with a deeply nested topology request, a port map, no output schema, and no sibling differentiation, the description is thin. It never says what a successful build produces (plan artifacts? a compiled project directory?), whether the project must already exist, or how this relates to hcl_stage_plan / hcl_open_project / hcl_validate_plan.

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% across 7 top-level parameters, and the description only directly explains `activate`. The large nested `request` topology object, `port_map`, `stage_name`, `project_path`, `hcl_pid`, and `idempotency_key` are left for the agent to infer ('open it in an existing GUI' only hints at hcl_pid; 'durable idempotency' only hints at idempotency_key).

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?

"Plan and compile an isolated HCL project, optionally open it in an existing GUI" gives a specific verb pair (plan, compile) plus the resource and an optional side action. It does not, however, distinguish itself from adjacent siblings such as hcl_plan_topology, hcl_stage_plan, hcl_load_plan, or hcl_open_project, so the agent must guess which of these to pick.

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?

"activate defaults false. No VM power or CLI deployment occurs" implicitly tells the agent this tool is not for deployment, and "offline builds" versus "live activation" implies a pre-deploy phase. But no sibling is named as an alternative (e.g. hcl_live_deploy for deployment, hcl_validate_plan for checking), and no prerequisite is stated, so the routing is only inferable.

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 establish that this is a read-only, idempotent, closed-world operation, so the bar is lower. The description adds useful context by clarifying that the tool is offline-only and produces documented Comware templates, which reinforces that no live device mutation occurs.

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?

It is a single compact sentence with the key output and constraint front-loaded. There is no wasted wording.

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

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

For a tool accepting a complex topology plan with many nested object types and no output schema, the description is too sparse. It does not explain the expected plan shape, what the generated templates contain, or how the ten service types are selected.

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 is a deeply nested TopologyPlan, and schema description coverage is 0%. The description only hints at 'ten typed services' without explaining the required plan structure, devices, links, services discriminator, or other significant fields.

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 output resource: generating documented Comware templates for ten typed services. It is clear enough to distinguish from deployment/operations siblings, though it does not explicitly name the closest sibling alternatives.

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

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

The phrase 'offline only' gives an important usage constraint, implying this is for template generation rather than live deployment. However, it does not say when to prefer this over siblings like hcl_generate_operations, hcl_full_build, or hcl_export_artifacts.

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 readOnly, idempotent, and non-destructive annotations already establish safety. The description adds useful behavioral context that the generated manifest is non-executable until live adapters are accepted, but it does not explain the manifest's contents, output shape, or how the executable flag changes.

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

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

The description is a single front-loaded sentence with no filler. It is concise and easy to scan, though its brevity contributes to gaps elsewhere.

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 accepting a large nested topology plan and returning a generated manifest with no output schema, the description is far too thin. It does not explain the expected plan structure, the meaning of 'include_configs', or what the resulting operation manifest contains.

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 never mentions the two top-level parameters, 'plan' or 'include_configs'. With a very large nested plan schema and no parameter prose, the description does not compensate for the coverage gap.

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

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

The description names a specific action and artifact: generating a declarative HCL operation manifest. However, it does not distinguish this from close siblings such as hcl_generate_configs, hcl_export_artifacts, or hcl_plan_topology, and 'operation manifest' remains undefined.

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 no guidance on when to use this tool versus generating configs, exporting artifacts, or planning topology. The 'executable=false until live adapters are accepted' caveat is a status note, not a selection guideline.

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 establish that this is a safe, read-only, idempotent operation. The description adds a cryptic caveat about never claiming guest CLI verification, which is useful context but not clearly explained; it does not describe data source, limitations, or freshness.

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 very short, front-loads the read action, and contains no filler. However, the second clause about guest CLI verification is opaque and may not earn its place without more context.

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

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

An output schema exists and annotations cover safety, reducing what the description must explain. Still, the single required parameter is undefined and the purpose is somewhat ambiguous between 'device details' and 'default interfaces', leaving minimum-viable but noticeable gaps.

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

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

Schema description coverage is 0%, so the description must compensate for the required 'model' parameter. It only says 'one installed model', which does not clarify whether 'model' is a device model name, identifier, label, or something else.

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 gives a specific verb ('Read') and resource ('installed model's default interfaces'), but it is ambiguous because the tool name says 'device details' while the description talks about a 'model' and only mentions interfaces. It partially distinguishes from list-style siblings but does not clearly establish that this retrieves device details.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as hcl_list_devices, hcl_inspect_project, or hcl_console_exec. The phrase 'one installed model' implies singular retrieval, but no conditions, exclusions, or sibling routing are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety behavior is covered. The description adds a useful limitation that carrier state does not prove cabling and health remains unknown, but it does not discuss timeout behavior, permissions, or output characteristics.

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 definition is two short sentences and front-loads the core action before adding a caveat about interpretation. There is no filler or redundant restatement of annotation 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?

For a four-parameter tool with no output schema and 0% schema description coverage, the description is too thin. It omits parameter meaning, expected output shape, and practical context for timeout or IPv6 inclusion.

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 0%, and the description does not mention project_path, topology, include_ipv6, or timeout_seconds. With four undocumented parameters, the description does nothing to compensate for the missing schema 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 states a specific read operation over a defined target: interface anomalies and repeated addresses from staged running guests. It is clearer than a generic health check, but it does not explicitly distinguish itself from nearby inspection tools such as hcl_verify_connectivity or hcl_inspect_ports.

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 implies the tool is for checking staged running guests, but gives no explicit when-to-use guidance or when-not-to-use conditions. No alternative sibling tools are named, so an agent must infer routing from the purpose sentence alone.

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

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

Annotations already establish readOnly/idempotent/non-destructive/closed-world, and the description adds genuine behavioral context beyond them: the default-to-all-staged-devices scope and the fact that only_linked=true will be rejected because link inventory is unverified. That error-path disclosure is valuable. It stops short of describing the shape of the returned state or the staging-vs-running distinction.

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 with the behavioral default stated first and the constraint second; there is no filler. It is terse to the point of cryptic in places, but nothing could be cut without losing information.

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

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

For a four-parameter tool with 0% schema coverage and no output schema, the description omits both required parameters and any hint of the returned interface state. An agent could not form a correct call from this text plus the schema alone.

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 carries the full burden, yet it only addresses two of four parameters and only partially: `device` (empty = all staged) and `only_linked` (rejected when true). The two REQUIRED parameters, `topology` and `project_path`, are never mentioned, leaving an agent with no format expectations for the mandatory inputs.

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?

It does use a concrete verb ("Read") and a resource ("interface state"), but "bound running-device interface state" is jargon-heavy and hard to parse, and it never names a sibling (e.g. hcl_bridge_status, hcl_read_vlans) to distinguish itself. An agent gets the rough idea that this reads port/interface state but not cleanly how it differs from the other read 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 one scoping rule (empty device inspects all staged devices) and one hard exclusion (only_linked=true is rejected), which is real guidance. However, it never says when to use this instead of the many neighboring inspection/read tools, so selection among siblings is left to inference.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds project-level scope and the fact that it returns devices and links, but it does not add deeper behavioral context such as error behavior or path requirements.

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

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

The description is a single front-loaded sentence with no wasted language. It states the action, object, scope, and non-mutating constraint efficiently.

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

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

For a simple one-parameter read-only tool with annotations and an output schema, the description covers the core action adequately. However, it leaves the parameter semantics and sibling-routing guidance under-specified.

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 only parameter, project_path, is not explained in the description. The phrase 'one saved HCL project' implies that the parameter selects a project, but it provides no details about the expected path format or validation.

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 ('Read') and names the resources ('devices and links') within a clearly bounded scope ('one saved HCL project'). This is clear, but it does not explicitly differentiate itself from nearby siblings such as hcl_list_devices, hcl_open_project, or hcl_backend_topology.

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

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

The phrase 'without changing it' implies read-only inspection, but the description gives no explicit guidance on when to choose this tool instead of alternatives like hcl_list_devices or hcl_open_project. There are no exclusions, prerequisites, or alternative-routing cues.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description adds that results carry 'file evidence and firmware boundaries', which is useful content context, but says nothing about scope, filtering, or ordering beyond that.

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

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

A single front-loaded sentence with no filler. The trailing phrase 'with file evidence and firmware boundaries' is slightly opaque but is the only place value beyond the schema is conveyed.

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 values need no explanation, and the zero-parameter read-only nature keeps demands low. However, with 51 sibling tools and several overlapping list/detail tools, the description should have clarified what 'model defaults' means and how this differs from hcl_get_device_details.

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

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

The tool takes zero parameters, and the empty schema is self-explanatory, so there is nothing for the description to disambiguate. Baseline 4 applies; the description neither helps nor misleads here.

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 verb 'List' plus the resource 'installed HCL model defaults' is specific enough to be actionable, but the phrasing drifts from the tool name (devices vs. model defaults), leaving it unclear whether this enumerates discovered devices, model definitions, or default settings. It does not distinguish itself from the nearby hcl_get_device_details or the other hcl_list_* siblings.

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

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

There is no statement of when to call this instead of hcl_get_device_details, hcl_list_projects, or hcl_list_templates, and no preconditions or exclusions are given. The agent must infer the usage context from the tool name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only an ambiguous caveat that model compatibility is unverified, without explaining what the tool actually reads or returns.

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

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

The description is a single short sentence with no wasted text, but it is not front-loaded with the tool's actual purpose and remains confusing rather than efficiently informative.

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

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

With one undocumented optional parameter, no output schema, and no explanation of what modules are or what is returned, the description leaves major gaps for an agent trying to 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?

Schema description coverage is 0% and the single optional model parameter is undocumented in the schema. The description mentions "model compatibility" but does not explain what the model parameter does, what format it expects, or how it affects the result.

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 says to "Read the documented native NIC mode and fixed profiles," but the tool is named hcl_list_modules. It does not clearly state that the tool lists modules, nor does it distinguish this operation from siblings like hcl_list_devices or hcl_capabilities.

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

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

There is no guidance on when to use this tool, when not to use it, or which sibling tools are alternatives. The sentence gives no selection criteria for an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description contributes the non-recursive scoping detail ("immediately under"), which is genuinely additive. It does not say what is returned when no roots are configured or whether roots must be preconfigured elsewhere.

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 the scope constraint front-loaded and no filler. Nothing could be removed without losing information.

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

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

With no parameters, full annotation coverage, and an output schema documenting return values, the description only needs to establish the list scope, which it does. The remaining gap is discovery context — where "configured project roots" come from and what an empty result means.

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 takes zero parameters, so there is nothing for the description to clarify; the baseline for a parameterless tool 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?

Specific verb ("List") plus resource ("HCL projects") with an explicit scope qualifier ("immediately under configured project roots"). It does not name a sibling or contrast with hcl_inspect_project / hcl_open_project, but the operation itself is unambiguous.

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

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

Usage is implied: an agent gathers projects under the configured roots. There is no explicit when-to-use statement and no routing to alternatives like hcl_inspect_project (for detail) or hcl_open_project (to open one), even though 50+ HCL siblings make that differentiation valuable.

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, and closed-world scope, so the safety profile is fully covered structurally. The description contributes essentially nothing beyond that: no mention of result count, ordering, pagination, or what a 'template' object contains.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though its brevity comes at the cost of substance rather than because the substance is already covered elsewhere.

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

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

For a zero-parameter, read-only list tool with no output schema, the definition is minimally adequate. It still leaves open what a 'deterministic HCL-native graph template' is and how it relates to plan/module tooling in this sibling set, which an agent would need to pick it confidently.

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 takes zero parameters, so by definition there is nothing to document and the baseline is 4. The description neither needs to nor does add parameter meaning.

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

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

The description names a specific verb (List) and a resource (HCL-native graph templates), so the operation is identifiable. However, 'deterministic HCL-native graph templates' is unexplained jargon and does nothing to distinguish it from siblings such as hcl_list_modules, hcl_list_projects, or hcl_list_devices, which are also listing 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?

There is no statement of when to use this tool, when not to, or which sibling to prefer for adjacent needs (e.g., hcl_list_modules or hcl_plan_topology). The agent must infer usage purely from the name.

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

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

The description adds real context beyond the annotations by disclosing that all staged devices are backed up first and modified devices are restored on failure. However, it doesn't say what 'gated' means operationally, whether a failed deploy leaves partial state, or that successful runs make irreversible changes despite the backup.

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?

Length is ideal (one short sentence, no filler), but it is front-loaded with secondary behavior instead of the primary action. It isn't verbose; it's misdirected.

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, non-idempotent mutation with three undocumented parameters and no output schema, that one sentence is not enough. It should state the deploy action, the gate/prerequisite, and what the return conveys about success or partial failure.

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 carry parameter meaning, yet it only indirectly touches 'devices' via 'all staged devices' and says nothing about project_path or topology. The scope of the devices list versus the topology target isn't clarified.

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?

'Deploy' appears only as a noun ('before deployment'); the actual action of the tool is never stated. The sentence describes the safety net (backup and restore) rather than the operation, leaving the agent to infer from the name that this pushes staged config to live devices.

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 call this instead of hcl_validate_plan, hcl_plan_topology, hcl_full_build, or hcl_parity_report, all of which are plausible prior steps. 'Gated' hints at a prerequisite but doesn't name it or explain what unlocking the gate requires.

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 establish that this is read-only, idempotent, non-destructive, and closed-world. Beyond that, the description adds useful behavioral context: it hash-checks the plan and does not open the HCL GUI, indicating a headless integrity-checking load path.

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 definition is a single front-loaded sentence with no filler. Every phrase contributes to purpose or behavior, and the key action comes first.

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

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

For a simple one-parameter read-only tool with rich annotations, the description is minimally viable but leaves out important details about the artifact directory and what happens on hash mismatch. No output schema exists, so the description could do more to explain the result of loading and checking the plan.

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

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

The schema has one required parameter, artifact_directory, with 0% description coverage. The description only links it indirectly through 'exported plan' and does not explain what the directory must contain, its expected layout, or whether the path must exist.

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 action and resource: 'Hash-check and reload an exported plan.' It is clear enough to distinguish this as a plan-loading/verification operation, but it does not explicitly contrast itself with nearby plan tools such as hcl_validate_plan or hcl_open_project.

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 is for reloading an exported plan, but it gives no explicit when-to-use guidance, prerequisites, or alternatives. It does not tell the agent when to choose this over hcl_validate_plan, hcl_stage_plan, or hcl_restore_config.

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

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

Annotations only declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds real context beyond them by flagging that the operation is write-gated and that it deliberately stops short of booting guests or running CLI deployment. It still omits what happens on a repeat call or on a mismatched client/pid, leaving the non-idempotent hint unelaborated.

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 dense sentence with no filler, and the scope constraint plus the excluded behaviors are front-loaded. It is close to optimally compact, though the abbreviations cost some clarity.

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-gated open operation with no output schema, the description covers the safety boundary but leaves the agent unsure what project_path must point at (a directory? a .net file?), what hcl_pid must designate, and what the call returns or mutates in the client. Adequate but with clear gaps.

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

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

Schema description coverage is 0% — both properties carry only bare titles ("Hcl Pid", "Project Path") — and the description says nothing about either. With two required parameters undocumented in both places, the description fails to compensate for the gap.

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

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

Names a concrete verb ("Open") and resource ("a staged .net") and scopes it to an existing SimwareClient, which is enough to distinguish it from a fresh load or a list of projects. The jargon (".net", "SimwareClient") is unexplained, so the purpose is clear in outline but not fully legible without domain knowledge.

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?

"In an existing SimwareClient" implies a prerequisite and "no guest boot or CLI deployment" implicitly steers an agent away from hcl_live_deploy, but no sibling is named and no explicit when-to-use condition is stated. Usage is inferable rather than instructed.

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 this as a read-only, idempotent, non-destructive, closed-world operation. The description adds that it compares a pinned mapping against current MCP discovery, which is useful context, but it does not explain the nature of the differences, prerequisites, or any behavioral edge cases.

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 with no filler. However, it is front-loaded with the vague term 'pinned mapping,' which makes the core purpose less immediately clear than it could be.

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 an output schema, zero parameters, and rich annotations, much of the necessary context is already provided. The description still leaves 'pinned mapping' undefined and does not clarify what kind of parity report is produced, which matters for a tool with a broad set of similarly named 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?

The tool has zero parameters, so the baseline is 4 per the scoring rules. The description correctly does not discuss parameters, and the schema confirms none are 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 gives a specific action ('Read') and a somewhat specific subject ('pinned mapping and API differences against current MCP discovery'), but 'pinned mapping' is undefined and the tool's exact purpose is still vague. It does not clearly differentiate this parity report from siblings such as hcl_capabilities, hcl_validate_plan, or hcl_diff.

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 offers no guidance on when to use this tool, when not to use it, or which sibling tool to choose instead. An agent must infer usage entirely from the name and vague description.

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 and openWorldHint=false, so the safety profile is fully covered. The description contributes only 'deterministic' (echoing idempotency) and 'never deploy' (echoing readOnly); it says nothing about what the plan contains, whether errors are raised for infeasible topologies, or how output is returned.

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

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

One sentence, front-loaded with the action and the input contract, with no filler. It is arguably over-terse given the request complexity, but nothing in it is wasted.

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 taking a deeply nested 30-field topology specification with no output schema, the description omits any explanation of the request structure, template selection, or what the returned plan looks like. The annotations carry the safety story, but the calling contract is not adequately covered.

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 single top-level 'request' parameter expands into ~30 nested fields (templates, pools, per-LAN counts, wireless settings) whose interactions are entirely undocumented in the description. Only 'strict TopologyRequest' hints at the request shape; the semantics of templates, custom_plan, and model overrides are left to the schema alone.

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

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

The verb+resource pair ('build a plan') is specific, and 'from a strict TopologyRequest' identifies the input contract. However, the sibling list contains hcl_stage_plan, hcl_estimate_plan, hcl_explain_plan, hcl_fix_plan, hcl_validate_plan and hcl_backend_topology, and the description gives no basis for choosing this one over any of them.

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

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

'Never deploy' is the only usage signal, and it merely states the tool does not mutate — which the annotations already say. There is no guidance on when to call this versus the other five plan-related siblings, nor on prerequisites (does a project need to be open first?).

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 fully declare the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's main added value is the qualifier 'native user-defined,' clarifying it returns user-configured rather than default QoS objects. It says nothing about error behavior for unbound devices or the shape of results.

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 efficient sentence with the resource and scope front-loaded and no filler. It is arguably too short for the amount of parameter ambiguity it leaves, but nothing in it is wasted.

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 no output schema the description covers what is retrieved, but it leaves the key precondition ('bound device') implicit and provides no indication of scope or filtering behavior tied to project_path/topology. Adequate but with clear gaps.

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

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

Schema description coverage is 0% and none of the three parameters (project_path, topology, device) are documented in either schema or description. The description only echoes 'device' and hints it must be bound, leaving project_path and topology entirely unexplained.

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 (Read) and concrete resources (traffic classes, behaviors and policies) scoped to 'one bound device,' which separates it from neighboring read tools like hcl_read_vlans and hcl_inspect_ports. It stops short of naming a sibling alternative but the subject matter is unambiguous.

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

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

The phrase 'from one bound device' implies the precondition that a device must already be bound in the topology, but there is no explicit when-to-use guidance, no mention of what to do if the device is unbound, and no named alternatives for related QoS inspection.

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, and openWorldHint=false, so the safety profile is fully covered. The description adds one meaningful behavioral note — returned data reflects real state with 'no default or capacity guesses' — but says nothing about scope of VLANs returned or failure modes for unbound devices.

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 compact sentence with the key scope constraint front-loaded and no filler. Slightly cryptic phrasing ('capacity guesses') is the only cost.

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?

Three required parameters are entirely undescribed, there is no output schema, and the description does not explain what 'native VLAN state' includes or the relationship between project_path, topology, and device. For a three-param read tool with zero schema coverage, this is under-specified.

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 all three parameters (project_path, topology, device) are undocumented in the schema. The description only loosely gestures at 'device' via 'one bound staged device' and gives no meaning for project_path or topology, so it fails to compensate for the coverage gap.

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

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

States a specific verb+resource: 'Read detailed native VLAN state,' scoped to 'one bound staged device.' The 'no default or capacity guesses' clause signals that values are actual device data rather than inferred, which helps distinguish it from planning/apply siblings like hcl_apply_vlan or hcl_estimate_plan, though it stops short of naming a specific alternative.

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

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

The phrase 'from one bound staged device' implies a precondition (the device must already be staged/bound), which is useful implicit guidance. However, it never states when to choose this over related read tools such as hcl_inspect_ports or hcl_read_qos, and no exclusions are given.

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, so the description's job is to add behavioral detail — and it does: a backup is taken, 'scope and startup readback' occurs, and unrelated definitions and bindings remain protected. That safety-net and blast-radius information is genuinely beyond the annotations. The dry_run escape hatch, however, is never mentioned.

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

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

Two tight sentences with the core action front-loaded and the protective behavior following. No filler, though the phrase 'Named types may be resolved from the actual config' is slightly opaque without knowing what 'types' refers to.

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 taking 5 parameters (4 required, one nested) with no output schema, the description covers side effects and safety well but leaves the dry_run preview option and the topology/device addressing model unaddressed. An agent knows what happens to the config but not how to test it safely first.

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 carry parameter meaning. It covers the identity of the ACL (numbered/named, resolved from live config) and hints at the binding interface, but acl_type, binding_direction, dry_run, project_path, topology and device are all left unexplained.

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 pairs a specific verb with a precise resource and scope: remove one exact numbered/named ACL plus an optional IPv4 binding. That scoping distinguishes it clearly from hcl_apply_acl and hcl_remove_nat in the sibling set, though it never names an alternative explicitly.

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 only implied by the verb 'Remove' — an agent can infer this is the removal path rather than the apply path. There is no statement of preconditions, no 'when not to use', and no pointer to hcl_apply_acl for modification instead of removal.

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. The description adds useful behavior beyond that: removal can include unshared ACL/pool resources, and reused operation keys return recorded receipts without replaying device commands. It still omits dry-run behavior and permission prerequisites, so it is not fully transparent.

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

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

The description is two front-loaded sentences with little waste: first scope, then reuse semantics. It is appropriately concise, though the term 'binding' is slightly opaque.

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, nested-parameter tool with no output schema and no schema field descriptions, two sentences are insufficient. Key operational details such as dry-run behavior, parameter roles, and destructive scope are not covered enough for an agent to invoke it confidently.

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 schema is nested, so the description must carry parameter meaning. It only vaguely maps to a few fields with phrases like 'exact NAT mappings' and 'optional unshared ACL/pool resources,' but does not explain router, mode, interfaces, dry_run, operation_key, timeout, or static mappings.

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: removing exact NAT mappings, plus related binding and optional ACL/pool resources. It is clear what the tool does, though it does not explicitly contrast itself with siblings such as hcl_apply_nat or hcl_remove_acl.

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 is the removal counterpart to NAT application, but gives no explicit when-to-use guidance, prerequisites, or alternatives. It also does not clarify when to choose this over hcl_remove_acl for ACL cleanup.

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, idempotentHint=false, so the mutation profile is known. The description adds useful context: it restores a *tested* backup and performs a running-config comparison afterward, plus a gating condition. However it never states what configuration is overwritten, whether rollback is possible, or what 'gated' concretely requires.

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

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

One front-loaded sentence with no filler, and both the restore action and the post-restore comparison are stated up front. '(gated)' is slightly opaque jargon but costs little.

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, non-idempotent restore with zero schema descriptions and no output schema, the description is thin: preconditions for the gate, what the comparison returns, and failure/rollback behavior are all unaddressed.

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% for all three required parameters (project_path, topology, backup_id), so the schema contributes nothing. The description only loosely implies backup_id via the word 'backup' and says nothing about project_path or topology, leaving the agent to guess formats and relationships.

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

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

The description names a specific verb ('Restore') and resource ('tested native backup'), plus secondary behavior ('compare the complete running configuration'). It clearly differs from siblings like hcl_backup_config and hcl_diff, though it never names those siblings explicitly.

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?

'tested native backup' and '(gated)' imply a precondition (backup must exist and be validated) but only by inference. There is no explicit when-to-use guidance, no exclusions, and no pointer to alternatives such as hcl_backup_config or hcl_diff.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is partly covered. The description adds genuinely new facts — that it verifies staged identity before writing, and that it parses files after saving — but leaves 'write-gated' undefined and does not say whether an existing save is overwritten or what happens on verification failure.

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 that names the action sequence in execution order with no filler. It is dense — three clauses plus a parenthetical — but nothing is redundant.

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 non-idempotent write tool with no output schema and two undocumented required parameters, the description should explain the gating condition, overwrite behavior, and what the post-save parsing produces. None of that is present, leaving an agent likely to call it without understanding the precondition or the side effects.

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% for both required parameters; hcl_pid and project_path have no descriptions at all. The description mentions 'active staged project identity' but never explains how project_path and hcl_pid relate to that identity or what format hcl_pid takes, so it fails to compensate for the coverage gap.

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

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

The description gives a specific compound action (verify identity, save, parse saved files) on a named resource (the active staged project), which is clearly distinguishable from siblings like hcl_open_project, hcl_inspect_project, or hcl_backup_config. It stops short of explicitly contrasting itself with any sibling, and 'verify identity' remains somewhat opaque.

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

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

There is no statement of when to call this versus hcl_open_project, hcl_backup_config, or hcl_full_build, nor any prerequisites (e.g. must a project be staged first, must it be validated). The parenthetical '(write-gated)' hints at a precondition but is never unpacked.

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 this is a non-readOnly, non-destructive, non-idempotent mutation with no open-world effects. The description adds one genuinely non-obvious behavioral fact: that the operation first copies the project, implying a broader side effect than a simple add. It does not clarify overwrite behavior, link failure handling, or idempotency semantics beyond the annotation.

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

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

One short, front-loaded sentence with no filler. It is concise but at the cost of under-specification for a 10-parameter mutation tool.

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 10 parameters, 6 required, zero schema coverage, and a mutation with a compound copy side effect, the description is far too thin. It does not explain coordinate semantics, linking behavior, or the idempotency key, leaving the agent unable to call this correctly without guessing.

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 across 10 parameters, the description carries the full burden but only loosely gestures at template_device ('cloned from a known model') and connect_to ('optionally link it'). Key parameters like x, y, new_name, new_port, idempotency_key, and stage_name are given no meaning at all.

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 sentence lists concrete verbs and resources (copy project, add device cloned from a model, optionally link), which is more specific than the name alone. However, the compound 'Copy a project' step is surprising for a tool named 'add_device' and is unexplained, and nothing distinguishes it from siblings like hcl_stage_copy, hcl_stage_link, or hcl_list_templates.

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 when-to-use guidance is provided. An agent cannot tell from the description when to prefer this over hcl_stage_copy plus hcl_stage_link, or what prerequisite stages/projects must exist first.

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=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false, so the safety profile is covered. The description adds only the vague notions of a "bounded" note and appending "to a copy," without explaining limits, permissions, whether the copy is returned, or how the operation behaves.

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?

It is a single short sentence, but the phrasing is awkward and under-specified rather than efficiently informative. The most important scoping details are missing, so brevity does not earn 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 mutation tool with six undocumented parameters, no output schema, and only baseline annotations, the description is far too thin. It supplies no parameter meanings, no return behavior, and no operational context needed 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 0% and the description mentions none of the six parameters. Required fields such as project_path, stage_name, x, y, and text are left completely unexplained, as is the optional idempotency_key.

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 says "Append a bounded note" which matches the tool name, but the target is described opaquely as "the observed .net representation" and "a copy." It does not clearly identify the project/stage or distinguish the operation from siblings like hcl_stage_clear_annotations.

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

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

There is no guidance on when to use this tool, when not to use it, or which sibling tool to choose instead. The description provides no contextual triggers or alternatives.

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

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

With annotations already declaring readOnlyHint=false, destructiveHint=false and openWorldHint=false, the description contributes real behavioral value by naming exactly what is deleted (observed NOTE blocks) and what is preserved (unknown drawing/Non-vBox data). It does not resolve the tension between a removal operation and destructiveHint=false, nor does it explain the optional idempotency_key while idempotentHint=false.

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

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

A single compact sentence with the destructive scope front-loaded ahead of the preservation guarantee; every clause carries information. It is arguably undersized for a three-parameter mutation tool, but there is no padding or 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 mutation tool with no output schema and zero parameter documentation, the description leaves out return behavior, whether the project is saved/persisted, what happens if no NOTE blocks exist, and the role of idempotency_key. It answers 'what is removed' adequately but not 'what does calling it actually do'.

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 none of the three parameters (project_path, stage_name, idempotency_key) are mentioned in the description. With low structured coverage the description should compensate, and it does not — an agent gets no hint about path format, stage scoping, or retry 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 ("Remove") and resource ("observed NOTE blocks") with an explicit scope limiter ("only"), which is far more informative than the tool name alone. It does not name the stage/project it operates on despite both being required parameters, and it does not differentiate itself from siblings like hcl_stage_add_note.

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 clarifies the blast radius (NOTE blocks only) but gives no guidance on when to invoke this tool versus alternatives, no preconditions, and no mention of when NOT to use it. An agent must infer from the sibling list that this is the counterpart to hcl_stage_add_note.

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

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

The annotations already declare that this is not read-only, not idempotent, not destructive, and closed-world; the description is consistent with that. It adds that the result is an isolated project for safe verification, but it does not explain what is copied, what side effects occur, or how the stage is initialized.

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

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

The description is a single front-loaded sentence with no wasted wording. Its brevity is appropriate structurally, though it leaves important details unstated.

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 and annotations exist, so return values and basic safety are partly covered. However, for a tool that creates a project from required path and stage inputs, the description is too sparse: it does not clarify parameter meaning, isolation behavior, or practical constraints.

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 does not explain any of the three parameters. The required project_path and stage_name are only loosely implied by "HCL project" and "stage," while idempotency_key is entirely unaddressed.

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 gives a clear verb and resource: "Create an isolated HCL project." It also adds a specific context ("safe live-gate verification"), but it does not distinguish itself from nearby project/stage siblings such as hcl_open_project or hcl_stage_plan.

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

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

The phrase "for safe live-gate verification" implies when the tool is useful, so usage is suggested rather than explicit. It does not state when not to use it or name an alternative tool for related project or stage operations.

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 declare destructiveHint=false, but the description says 'Remove one saved device and reciprocal links,' which describes a destructive deletion. Although the description adds useful scope ('reciprocal links' and 'separate project copy'), the contradiction with destructiveHint=false is serious.

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

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

The description is a single front-loaded sentence with no filler. Its terseness contributes to missing details elsewhere, but the sentence itself is efficiently 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 mutating tool with no output schema and contradictory annotations, the description omits stage scope, idempotency semantics, and safety/rollback behavior. It gives only the removal scope, so an agent lacks enough context to call it confidently.

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 only vaguely implies 'device' and 'separate project copy'; it never explains project_path, stage_name, or idempotency_key. With four parameters and no schema descriptions, this is inadequate compensation.

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 gives a specific verb ('Remove') and resource ('one saved device and reciprocal links') plus a scope ('separate project copy'). This distinguishes it from add/rename/move siblings, but it does not explicitly name alternatives such as hcl_stage_unlink, so it falls short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of sibling tools like hcl_stage_unlink or hcl_stage_add_device. The phrase 'separate project copy' only hints at context without explaining selection 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?

Annotations already flag this as a non-idempotent mutation (readOnlyHint=false, idempotentHint=false), but the description adds little beyond the fact that a project is copied. It does not say what gets created, where the copy lands, whether an existing stage is overwritten, or what the 'reciprocal link' means operationally.

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?

It is a single efficient sentence with the primary action front-loaded, but the brevity is achieved by omission rather than precision, leaving essential behavior unstated.

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 7-parameter mutation tool with no parameter documentation and only weak annotation coverage, the description is far too thin. The presence of an output schema relieves some return-value burden, but an agent still lacks the context needed to invoke this 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 0% across 7 parameters, and the description only obliquely accounts for a/a_port/b/b_port ('two free ports'). It never explains the difference between 'a' and 'a_port', what project_path or stage_name do, or how idempotency_key behaves, so the cryptic parameter names remain opaque.

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 gives a specific compound verb+resource: copying a project and adding a reciprocal link between two ports, which lets an agent separate it from hcl_stage_copy at a high level. It is not fully self-sufficient because it never explains what 'stage', 'a', 'b', or 'free ports' mean in this system.

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

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

There is no guidance on when this tool should be chosen over the close sibling hcl_stage_copy or hcl_stage_unlink, and no prerequisites or exclusions are mentioned. The agent must infer the use case from the name and one-line description.

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=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds useful isolation semantics ('no live canvas mutation'), but it doesn't explain the role of idempotency_key, preconditions on project/stage, or what happens if the device doesn't exist.

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

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

One compact sentence, front-loaded with the core action and immediately qualified by the isolation constraint. No filler.

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

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

For a six-parameter mutation with no output schema and no annotations covering parameters, the description is too thin. An agent still lacks coordinate units/frame, whether the stage must pre-exist, whether the device must already be in the stage, and how idempotency_key behaves.

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% across six parameters, so the description must carry the burden and largely doesn't. 'Device' and 'isolated project copy' weakly hint at the device and project_path/stage_name parameters, but coordinates (x, y) and idempotency_key receive no explanation at all.

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 ('Move one saved device') and scopes it to 'an isolated project copy,' which clearly distinguishes it from live-mutation siblings like hcl_live_deploy and from hcl_stage_add_device. It stops short of naming a sibling alternative explicitly.

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

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

The phrase 'in an isolated project copy; no live canvas mutation' implies this is a staging-only operation and not a live edit, giving some selection context. However, it never says when to prefer this over hcl_stage_add_device, hcl_stage_rename_device, or when a staged project must already exist.

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 (which only say non-readonly, non-destructive, non-idempotent), the description states the mutation is confined to a separate copy, that source devices/notes are replaced in that copy, and that transcripts are kept out of startup configs. Those are concrete behavioral facts an agent could not infer from the schema. It still omits failure modes and how the stage is later applied.

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

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

Four short sentences, but they are telegraphic fragments ("Replaces source devices/notes in the copy.") and rely on unexplained jargon like "model-to-scene map" and "real source models." The key constraint about port_map arrives mid-description rather than up front.

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

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

No output schema exists and the input is a large nested topology plan, so the description should say what a successful stage produces and where it lands. It conveys the negative claims well (nothing is deployed or powered) but leaves the result artifact, error conditions, and the role of project_path/stage_name undefined.

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 carries the full burden, yet it explains only port_map ("every linked CLI port needs an explicit model-to-scene map"). It says nothing about project_path, stage_name, the structure of plan, or idempotency_key — the last being especially notable since annotations declare idempotentHint=false.

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 gives a verb and resource ("Compile a validated plan into a separate .net project"), but "compile" and "stage" are used loosely and the phrasing is unusual enough that an agent cannot easily tell this apart from siblings like hcl_stage_copy or hcl_full_build. The scope statement (staged result claims no GUI/VM/power/deploy) is more informative than the core purpose sentence.

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?

"Compile a validated plan" implies hcl_validate_plan should run first, and the port_map sentence hints at a precondition, but neither is stated as an explicit prerequisite or as an alternative to other staging tools. The negative claims (no GUI open, no deployment, no connectivity) sketch the boundary of what this tool is not, which is useful but indirect guidance.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=false, so the safety profile is covered. The description usefully adds that renaming cascades to both ends of saved links, which is behavior beyond the annotations, but it does not explain what 'new project copy' means, whether the rename is reversible, or how the optional idempotency_key interacts with the non-idempotent hint.

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

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

A single front-loaded sentence with no filler. Every clause carries content, although the ambiguous 'in a new project copy' phrase slightly undermines clarity rather than conciseness.

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

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

For a five-parameter mutation tool with 0% schema description coverage and no output schema, the description is far too thin. It omits parameter meaning, prerequisites (stage/project context), and the effect on existing link names, leaving the agent without enough information to call it confidently.

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 all five parameters (project_path, stage_name, device, new_name, idempotency_key) rely on bare titles. The description only implicitly references 'device' and 'new_name'; it never explains stage_name, project_path, or idempotency_key, so it fails to compensate for the schema gap.

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

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

States a specific verb and resource ('Rename one device') plus a notable side effect ('both ends of its saved links') and a scope ('in a new project copy'). It is clearly distinguishable from destructive siblings like hcl_stage_delete_device, though the phrase 'new project copy' is ambiguous and the stage context is never mentioned.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance and names no alternative (e.g., hcl_stage_move_device, hcl_stage_delete_device, hcl_stage_unlink). The operation is implied by the verb 'Rename', but an agent is left to infer the appropriate context entirely.

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 this is a non-read-only, non-idempotent, non-destructive mutation. The description adds the useful constraint 'exactly one reciprocal' (a paired link, one at a time), which is real behavioral context. It does not say what happens if the link is absent, whether the change is undoable, or what permissions the stage requires.

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

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

A single front-loaded sentence with no filler; the verb and object arrive immediately. It is arguably under-specified rather than verbose, which is a completeness problem rather than a conciseness one.

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 7-parameter mutation tool with no output schema and zero schema coverage, the description is far too thin. An agent cannot tell which port names belong to which device, what format the endpoints take, or how idempotency_key should be used to retry a non-idempotent removal.

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% across 7 parameters, so the description is the only place parameter meaning could come from, and it names none of them. Only the phrase 'reciprocal' faintly hints that a/b and a_port/b_port are the two endpoints of the link; stage_name, project_path, and idempotency_key are entirely unexplained.

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 ('Remove'), resource ('reciprocal saved link'), and scope ('isolated copy'), which is enough to separate it from hcl_stage_link, the obvious inverse sibling. It falls short of 5 because the 'isolated copy' wording is the only signal of the staging context and the description never names the sibling it contrasts with.

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?

'From an isolated copy' implies this is the staged-edit counterpart to a live operation, giving the agent implied context. But there is no explicit when-to-use, no when-not, and no named alternative such as hcl_stage_link or hcl_remove_acl, so the agent must infer the routing.

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 read-only, idempotent, non-destructive, so the safety bar is lower; the description still adds real value with its default structural requirement (connected declared wired topology) and its explicit limits ('does not prove firmware support, deployment or actual network connectivity'). The Comware-vs-.net port key naming rule is also behaviorally important, since a wrong key silently changes validation outcomes. It falls short of a 5 only because the failure/error behavior and what specifically gets rejected are unstated.

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?

It is short, but the phrasing is awkward and the final sentence drops its subject ('configuration checks individual intents...'), so the reader must infer that 'configuration' is the enum value. The most important behavior — the default topology requirement — is present but buried mid-sentence rather than 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 output schema exists, so return values need no explanation, and the safety caveats about what validation does not prove are covered. Against a 0%-described, deeply nested plan schema, though, the definition leaves an agent without enough guidance to construct a valid plan reliably; the interface naming hint is the only concrete input synthesis help.

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 'plan' parameter is an enormous nested structure (devices, links, addresses, services, subinterfaces, etc.) with no field-level documentation anywhere — the description says nothing about how to populate it. It does decode the validation_level enum by describing both modes, which is genuine added meaning, but that only covers one of two parameters and leaves the dominant one unexplained.

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 verb 'validate' and the object 'intent/plan' are present, so an agent can tell this checks a topology plan. But 'validate intent' is vague jargon, and nothing distinguishes it from nearby siblings like hcl_explain_plan, hcl_estimate_plan, hcl_fix_plan, or hcl_plan_topology. The reader knows roughly what it does but not how it differs from its neighbors.

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 contrast between the two validation levels ('by default require a connected declared wired topology' vs. 'configuration checks individual intents without requiring one wired component') does imply when each mode applies. There is no guidance at all on when to choose this tool over hcl_explain_plan, hcl_estimate_plan, or hcl_fix_plan, which is the harder selection decision.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds useful behavioral context by warning to parse actual ping statistics and never infer success from exit status, but it does not explain the implications of running against an open-world staged console or what side effects may occur.

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 definition is a single front-loaded sentence with no wasted text. It is efficient, though some terms such as 'bound staged console' are jargon-heavy and could be clearer.

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 and no parameter documentation beyond unlabeled schema fields. For a five-parameter connectivity verification tool, the description should do more to explain inputs, expected output, and how the result should be interpreted.

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% across five parameters, including project_path, topology, device, destination, and count. The description does not define these parameters or clarify how 'bounded' relates to count, leaving parameter meaning almost entirely to the bare schema titles.

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

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

The description names a specific action and resource: parsing bounded actual ping statistics from a bound staged console. It is clear what the tool does, though it does not explicitly differentiate itself from connectivity-related siblings such as hcl_health_check or hcl_console_exec.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. It implies use for connectivity verification but does not state prerequisites, exclusions, or sibling routing.

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