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

With only readOnlyHint=true annotated, the description adds real behavior: it pulls get_bgp_neighbors, orders findings worst-first, and each finding cites session state (is_up/is_enabled) or uptime along with a cause and a suggested action. That disclosure of output shape and remediation content goes beyond the annotation, though severity thresholds and handling of an unreachable device are not covered.

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 [READ] tag and the core purpose in the first line, then supporting detail, then args. Every sentence carries information, though the multi-line Args block is slightly heavier than needed for a single self-documenting parameter.

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 takes on return-value explanation and does so at a useful level (worst-first findings with state, cause, action). Combined with the default-device parameter semantics, the definition is complete enough to invoke correctly, with only threshold/scoring details left unspecified.

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

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

Schema description coverage is 0%, so the description must carry the parameter. It does explain that target is a device name from config and that omitting it falls back to the default device, which is meaning the schema (a bare nullable string with default null) does not provide.

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 (flag) plus resource (BGP neighbors) and enumerates the exact fault conditions it looks for (down, shut, recently reset, route-less). It also clarifies its relationship to the sibling get_bgp_neighbors by describing itself as an analysis layer that pulls that tool's data and reports worst-first findings, so an agent can distinguish raw retrieval from RCA.

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

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

Usage context is implied by the fault-oriented framing (use it when diagnosing unhealthy BGP sessions), and it names get_bgp_neighbors as its data source, which hints at when raw data is preferable. However, there is no explicit when-to-use versus when-to-use-an-alternative rule and no stated prerequisites.

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

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

Carries the full disclosure burden despite only readOnlyHint being annotated: it names exactly what is redacted, notes the 'redaction' block, and candidly flags the limits ('pattern-based across five vendor syntaxes ... cannot see multi-line PKI key blocks'). It also warns that include_secrets leaks secrets into the transcript. This is unusually rich 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?

Front-loaded with the [READ] tag and core purpose, then structured into behavior, caveats, and args. It is longer than strictly necessary and repeats the redaction point somewhat, but every sentence carries substantive 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 output schema, the description still explains the return shape (raw config plus a 'redaction' block with line counts) and covers both parameters and the safety caveats. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does: include_secrets is defined as returning the verbatim config with an explicit data-persistence warning, and target is described as the device name with a stated default-when-omitted behavior. Both parameters are fully explained beyond the bare schema types.

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 ('Return the device running config') and adds the key modifier ('credential values masked by default'). This separates it cleanly from siblings like config_diff, config_merge, and config_replace, which manipulate rather than read the config.

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 explicit direction on the include_secrets-vs-CLI decision ('Prefer the CLI's -o <path> flag ... when a human needs the real config'), which is real guidance, not inference. It does not, however, state when to pick this over the sibling read tools (e.g., device_facts) or any exclusions, so it stops short of a full 5.

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

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

Beyond the readOnlyHint annotation, it discloses that nothing is committed, that the diff is credential-redacted like config_backup, why redaction is needed, and that the result includes a redaction block with a count. It also explains the include_secrets trade-off for verbatim output. This is rich, consistent 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?

It is front-loaded with the [READ] DRY-RUN label and core promise, then uses a compact Args list. The redaction explanation is the only longer passage and it earns its place by clarifying a non-obvious side effect.

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 4-parameter dry-run tool with no output schema and only readOnlyHint in annotations, the description supplies enough context: commit behavior, redaction behavior, parameter meanings, and the returned redaction block. No critical gap remains 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?

With 0% schema description coverage, the description fully compensates by documenting all four arguments: config_text's merge vs. replace meaning, replace's full-config behavior, include_secrets' verbatim use case, and target's device-name role. It adds semantics the schema lacks.

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

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

The description opens with a specific verb and resource: '[READ] DRY-RUN: stage a candidate, return the diff, then discard it.' It immediately distinguishes itself from committing siblings with 'Nothing is committed' and 'dry-run primitive for previewing a change.' An agent can tell this is the preview-only path without opening other schemas.

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

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

It gives clear context for use—previewing a change—and specific guidance for the include_secrets flag ('use when verifying that the literal key you are pushing is the one that will land'). It does not explicitly name config_merge, config_replace, or confirm_commit as the committing alternatives, so the when-not-to-use boundary 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 only give destructiveHint=true; the description goes far beyond by disclosing the device-side auto-revert unless confirm_commit follows, the commit.safetyNet/commit.warning signal for drivers that cannot arm a timer, credential redaction with no opt-out, and that the full config is withheld but retained in undo.db. These are exactly the behaviors an agent cannot infer from 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?

The [WRITE] marker and revert-timer constraint are front-loaded and each paragraph earns its place by covering behavior, return values, and args. It is dense and slightly long, 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 destructive 4-param tool with no output schema, the description still explains the return payload (diff, backup digest with size+sha256, commit.safetyNet, commit.warning) and the whole confirm/rollback lifecycle. Nothing an agent needs to call or reason about the result is missing.

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

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

With 0% schema coverage, the description carries the full burden and does: revert_in default 300 and the non-obvious '0 disables it, leaving the recorded undo as the only rollback path', dry_run's preview+discard semantics, target as a device name from config, and config_text as the snippet. This adds meaning well past the bare schema types.

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 ('Merge a config snippet') plus the distinctive revert-timer commit model, which no sibling (config_replace, config_backup) shares. An agent can identify this as the safety-netted staged commit path without opening the schema.

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

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

Explicitly prescribes the workflow: 'Verify reachability, THEN call confirm_commit', and routes to config_diff(include_secrets=True) when a literal key must be verified. It also explains when to use dry_run and what it guarantees, so alternatives and conditions are both covered.

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

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

Adds substantial behavior beyond the annotations: the revert-timer mechanism, the commit.safetyNet field semantics, the undo.db (0600) backup retention, credential redaction with no opt-out, and the guarantee that dry_run previews cannot disagree with the real commit. These are exactly the failure-mode and side-effect details an agent needs for a destructive write.

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

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

Well front-loaded with the [WRITE]/HIGH RISK tag and organized into contract, returns, and args sections. It is dense and slightly long, but nearly every clause carries behavioral information; only minor tightening is possible.

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?

Although there is no output schema, the description explains the return shape (diff and backup digest) and what is withheld (raw config in undo.db, redacted diff). Combined with the commit-confirm contract and dry_run semantics, an agent has everything needed 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?

With schema description coverage at 0%, the description carries the full burden and does so: it explains revert_in default (300) and the special meaning of 0 (disables timer, undo becomes only rollback), dry_run's preview-plus-refusal behavior, target's source, and config_text's role as the complete replacement payload. This adds semantics well beyond the bare schema types.

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 ('Replace the full config') and immediately distinguishes scope with 'full replacement' versus the sibling config_merge, which merges. The [WRITE] tag and 'HIGH RISK' warning front-load the operation class so an agent can differentiate it from read siblings at a glance.

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

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

Explicitly describes the commit-confirm contract, tells the agent to verify reachability first then confirm via confirm_commit, and names the alternative path (config_diff(include_secrets=True)) for verifying a literal key. It also clarifies when the change is permanent (no timer armed) versus revertible, which is real when/when-not 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, but the description adds genuinely non-obvious context: 'No undo' (irreversibility), platform-varying rollback depth, and the fact that dry_run opens a session, verifies reachability, and returns a digest of the state that would be replaced. This goes well beyond what the annotations provide.

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

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

Front-loads the [WRITE] tag and the core action, then layers caveats and a parameter block. Every sentence earns its place, though the dry_run sentence is dense and could be trimmed slightly.

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, no-output-schema mutation tool with annotations covering the safety profile, the description supplies the irreversibility, device-variability, and dry_run return behavior an agent needs. Nothing critical is missing given there is no output schema to explain.

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 carries the burden. It documents both parameters: dry_run's verify-and-report semantics and target as 'Device name from config.' Minor gap on what a null/default target resolves to, but overall strong compensation for the empty schema.

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

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

States a specific verb+resource (revert the last committed change) and names the underlying mechanism (NAPALM rollback()), plus the [WRITE] classification. This clearly separates it from siblings like config_replace, config_merge, and undo_apply.

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 scope 'last committed change' implies when it applies, and 'dry_run=True' explains a safe preview path. However, it never explicitly contrasts with the closest alternatives (undo_apply, undo_list, config_replace), leaving the agent to infer which to pick — implied rather than stated usage.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true; the description adds real context beyond them by explaining the commit-confirm/revert-timer mechanism and warning that confirming locks in the change rather than allowing auto-revert. It does not address idempotency (annotations say non-idempotent) or what happens when no pending commit exists, so it stops short of full disclosure.

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

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

Front-loaded with the write marker and core purpose, then workflow context, then a structured Args section. Slight redundancy between the prose dry_run explanation and the Args entry repeats the same idea twice, which trims a point but does not impede scanning.

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

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

No output schema exists, and the description supplies the workflow position (second half of commit-confirm), the risk framing, the safe default, and both parameter meanings. An agent can call this correctly with what is provided; remaining edge cases (no pending commit, failure handling) are minor for this workflow tool.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: dry_run is defined semantically ('report whether a pending commit exists without confirming') and target is identified as a 'Device name from config.' Neither default value nor anyOf/null semantics are restated, but the behavioral meaning of both parameters is conveyed.

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?

Opens with a bracketed [WRITE] marker and a specific verb+resource ('Confirm a pending commit-confirm change'), plus the concrete effect ('cancelling its revert timer'). This clearly separates it from siblings like config_rollback and undo_apply, which operate on already-committed state rather than a pending confirm.

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

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

Explicitly states the precondition ('Run it only AFTER verifying the device is still reachable and healthy') and names the alternative course of action ('doing nothing is the safe alternative, because the device then reverts on its own'). It also routes the read-only case to dry_run=True, covering both modes.

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?

readOnlyHint already declares this as a safe read, and the redundant "[READ]" tag adds nothing beyond it. The description does add real value by disclosing the returned content and the interface-name-list side output, which matters since there is no output schema. It stops short of any deeper behavioral context (auth/permission needs, error conditions).

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 purpose statement followed by the sibling boundary and a labeled Args section - a clean, scannable structure. The "[READ]" prefix and minor line-wrapping are the only mild noise; nothing else 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?

With no output schema, the description correctly carries the return-value burden and lists the salient fields plus the interface-name side output. For a single optional-parameter read tool this is nearly sufficient; slightly more detail on return shape or target-resolution failure would make it complete.

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

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

Schema description coverage is 0% and the sole parameter carries no documentation in the schema, so the description does the work. "Device name from config; omit to use the default device" defines both the value source and the omitted-value behavior, compensating well 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 resource (device facts) and enumerates exactly what comes back: hostname, vendor, model, OS version, serial, uptime. It also carves out the boundary with the closest sibling by naming get_interfaces for per-interface state/speed, so an agent can tell the two apart without opening either schema.

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

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

Explicitly routes one case to an alternative ("Use get_interfaces for per-interface state/speed") and explains the target argument's default behavior ("omit to use the default device"). It doesn't broadly position device_facts against the other device-level siblings (get_environment, device_health, get_optics), but the key ambiguity is resolved.

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 readOnlyHint=true; the description adds genuinely non-obvious behavior: graceful degradation when a driver lacks get_environment (the section degrades to a note) and the presence of a 'healthy' flag plus an 'issues' list. No contradiction with the read-only annotation, though rate limits / cost of aggregation are unaddressed.

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 a [READ] tag and the core aggregation scope in the first clause; the degradation note and return-shape sentence each carry information. Slightly verbose in the 'Args:' block format, but no filler sentences.

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

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

There is no output schema, so the description usefully names the return contract ('healthy' flag, 'issues' list) and flags partial-failure behavior. Complete enough to call safely; the only gap is guidance on alternative diagnostic tools when issues are reported.

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

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

Schema coverage is 0% and the schema itself says nothing about target beyond string|null. The description compensates well by explaining the value source ('Device name from config') and the default behavior when omitted, which the schema's bare default:null does not convey.

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 composite resource (aggregated health = facts + interface up/down counts + environment) with enough specificity to distinguish it from sibling primitives like device_facts, get_interfaces and interface_health_rca. An agent can tell this is an umbrella roll-up rather than a raw data getter without opening any schema.

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

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

The description implies a 'one-shot health check' use case but never says when to prefer it over device_facts + get_interfaces, nor when to escalate to interface_health_rca or bgp_neighbor_rca for diagnosis. It does give practical arg guidance (omit target to use the configured default), which is context, not a when-to-use rule.

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

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

Annotations already declare readOnlyHint=true, and the description's '[READ]' marker is consistent. It adds the returned fields, which is useful, but does not disclose target omission behavior or any other operational detail beyond the safety 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 front-loaded with the key resource and returned fields, followed by a compact Args section. Every part is useful, with 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 simple read tool with a readOnly annotation and no output schema, the description covers the resource, returned fields, and parameter meaning. However, it leaves the behavior when target is omitted unspecified, which could matter since the parameter is optional.

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 load. It does explain the single parameter: 'target: Device name from config,' which adds meaning beyond the bare string/null schema, though it omits optional/default behavior.

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 resource – ARP table entries – and enumerates the fields returned (interface, IP, MAC, age). It is clear what the tool retrieves, though it does not explicitly distinguish itself from siblings like get_mac_address_table.

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 context, prerequisites, or alternatives are given. The description only states what the tool returns; an agent must infer that this is for ARP inspection when needed.

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

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

Annotations already declare readOnlyHint=true, and the '[READ]' tag merely reinforces that. The description adds useful non-obvious context by naming the returned data ('peer, remote AS, up state, prefix counts'), which helps the agent know what it will get back even without an output schema, though it says nothing about auth, scope, or pagination.

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?

Tight and front-loaded: the '[READ]' prefix and purpose sentence come first, then a compact args block. No filler, though it is arguably too sparse rather than genuinely optimized.

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 tool with no output schema, listing returned fields is the right compensation, and the lone parameter is documented. But it omits any differentiation from get_bgp_neighbors_detail and provides no scope or prerequisite context, leaving clear gaps for an agent choosing among 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?

Schema description coverage is 0%, so the description must carry the param burden, and it does document the single 'target' param as the device name from config. That is enough to be usable but adds no format, required/optional, or default semantics beyond the schema's own 'default: null'.

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 ('BGP neighbors per VRF') and lists the returned fields (peer, remote AS, up state, prefix counts), so the agent knows exactly what this fetches. However, it does not distinguish itself from the close sibling get_bgp_neighbors_detail, which an agent would have to open both schemas to disambiguate.

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 or when-not-to-use guidance, and no mention of the sibling get_bgp_neighbors_detail that covers a related read. The '[READ]' tag implies a read-only lookup, but nothing tells the agent when this tool is the right choice over 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?

The readOnlyHint annotation already establishes that this is a safe read operation, so the bar for extra behavioral disclosure is lower. The description adds the '[READ]' marker and lists the data available per VRF, but does not disclose permissions, failure behavior, or any operational side effects.

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

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

The description is short and front-loaded, starting with the read operation and scope before listing the optional argument. Every sentence adds useful information with no redundant filler.

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

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

For a simple read tool with one optional parameter and no output schema, the description gives enough to invoke it correctly by explaining the default-device behavior. The main remaining gap is the lack of explicit routing relative to get_bgp_neighbors.

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 explains that target is a device name from config and that omitting it uses the default device, which is exactly the context needed for the single optional parameter.

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

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

The description states a clear read operation and resource: detailed BGP neighbor information per VRF, including state, router ID, AS, and prefix stats. It does not explicitly distinguish this tool from the sibling get_bgp_neighbors, 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?

The description says to omit target to use the default device, which is parameter usage rather than tool-selection guidance. It does not say when to use this tool instead of get_bgp_neighbors, bgp_neighbor_rca, or other BGP-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?

readOnlyHint=true already declares this is a safe read, and the '[READ]' prefix is consistent with it. The description adds the useful detail that the payload covers five specific hardware categories, but says nothing about response shape, timing, or device-access requirements 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?

Two tight lines with the resource scope front-loaded and the parameter note separated into an Args block. No filler sentences.

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

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

For a one-parameter, read-only tool with no output schema, the definition covers purpose, scope, and the optional-target default. Only anticipated return format and any device-not-found behavior are unaddressed, which is a minor 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%, so the description carries the burden for the single parameter, and it does: it defines target as a device name from config and explains the default-device behavior when omitted. That is meaningful semantics the schema lacks, though it does not describe expected name 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?

The description states a specific verb and resource ([READ] Hardware environment) and enumerates what it covers: fans, temperature, power, CPU, memory. This lets an agent distinguish it from sensor-specific siblings like get_optics or interface-oriented ones like get_interfaces_counters, 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?

Beyond the '[READ]' tag and the target-default note, there is no guidance on when to choose this over adjacent tools such as device_health or device_facts, nor any prerequisite or exclusion. The usage must be inferred from the resource 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?

readOnlyHint=true already establishes this is a safe, non-mutating read, and the '[READ]' tag merely repeats that. The description does add value by naming the fields the agent will receive, which is useful given there is no output schema, but it discloses nothing about result size, filtering, or device reachability.

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 of purpose plus a compact Args block; front-loaded and free of filler. The Google-style Args formatting is boilerplate-heavy for a single parameter but not wasteful.

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

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

For a single-parameter read tool with no output schema and readOnly annotations, the description is adequate: it describes the returned fields in lieu of a schema. It falls short on the optional/null target semantics and on any indication of scope or result volume.

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 does partially: 'Device name from config' clarifies that target is a config-defined device name. It does not explain the null/default behavior (the parameter is optional with default null) or what happens if the target is omitted.

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 the resource (interfaces) and enumerates the attributes returned (up/down state, enabled flag, speed, description), so an agent can distinguish it from get_interfaces_ip and get_interfaces_counters. The verb is only implied via the '[READ]' tag rather than stated, but the scope is clear.

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

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

There is no when-to-use or when-not-to-use guidance and no reference to alternatives such as get_interfaces_ip or get_interfaces_counters for related data. The only prose is an argument glossary, leaving selection between the many sibling 'get_*' tools 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?

readOnlyHint=true already declares the safe-read profile, and the '[READ]' prefix merely restates it without adding anything. No mention of whether counters are cumulative or interval-based, what happens on an unknown target, rate limits, or failure modes—so the description contributes almost nothing 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 front-loaded sentence plus a one-line arg gloss; every fragment carries information and nothing is padded. Ideal signal-to-noise for a simple getter.

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

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

With no output schema, the description partially compensates by listing the counter families returned, which is the right instinct. However it leaves the optional-but-defaulted target behavior unexplained and says nothing about result scoping (per-interface records, ordering, or whether all interfaces are returned), leaving real gaps for a tool whose output shape is 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 coverage is 0% and the single 'target' parameter is only typed as a nullable string with a null default, so the description's 'Device name from config' is genuinely additive—it tells the agent where the identifier comes from. It still omits whether target is optional, what happens if omitted (all devices? local device?), and any naming 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?

The description names a specific resource (per-interface counters) and enumerates what is counted (octets, packets, errors, discards), which clearly separates it from the config-oriented sibling get_interfaces and from get_interfaces_ip. It never names an alternative tool explicitly, so it stops short of full sibling differentiation.

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

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

Usage is only implied by the '[READ]' tag and the counter-focused scope; there is no explicit statement of when to reach for this versus get_interfaces, interface_health_rca, or get_interfaces_ip. A capable agent can infer intent, but the definition offers no routing guidance.

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

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

Annotations already declare readOnlyHint=true, and the description's '[READ]' marker merely restates that, so no credit there. What it does add is that results are per-interface and cover both IPv4 and IPv6 with prefix lengths, which is genuine behavioral context. It says nothing about pagination, device reachability failures, or whether a missing target means all devices, leaving real gaps for a tool with only annotation coverage of safety.

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 lines, front-loaded with the scope marker and the return content before the Args block. Every element is short and readable, though the '[READ]' prefix is redundant with the annotation and the Args section is formatted for a docstring rather than for agent parsing.

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 should characterize the return value; it does so only in one clause ('per-interface IPv4/IPv6 addresses and prefix lengths') without indicating the shape (interface-keyed mapping) or empty/missing-device behavior. For a single-parameter read tool this is adequate but marginal.

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 burden, and it does partly by defining target as 'Device name from config'. However, it does not explain that target is optional with a null default, nor what behavior results when it is omitted (all devices vs error), which is the most important ambiguity for this single parameter.

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

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

States a specific resource (per-interface IPv4/IPv6 addresses and prefix lengths) and the implied retrieval verb, so an agent can distinguish it from the plain get_interfaces sibling by the IP/prefix payoff. It stops short of explicitly naming or contrasting with get_interfaces, so the differentiation is inferred rather than stated.

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

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

The '[READ]' tag hints at a safe read context, but there is no statement of when to call this versus get_interfaces, get_interfaces_counters, or device_facts. No prerequisites, no exclusions, no alternatives — usage is left entirely to inference 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 annotations already declare readOnlyHint=true, so the '[READ]' tag is largely redundant with structured data. The description does add the return payload shape, which is useful for a read tool, but it omits behavior for the defaulted null target (does it query all devices or fail?) and any rate-limit or inventory-source caveats.

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

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

Very short and front-loaded: the resource and payload lead, and the parameter note follows. Every sentence earns its place, though the 'Args:' block formatting is boilerplate rather than tailored.

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, listing the returned fields is important and partially covers the gap. But the optional/defaulted target and the absence of any routing to get_lldp_neighbors_detail leave the definition barely sufficient for reliable invocation in a 35-tool suite.

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, and it does explain that target refers to a device name sourced 'from config' — more than the bare schema title 'Target' offers. However, it never clarifies that the parameter is optional with default null, nor what null means semantically, leaving a genuine ambiguity.

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 (LLDP neighbors) and enumerates the returned fields (local port, remote hostname, remote port), so the agent knows exactly what comes back. It does not explicitly differentiate itself from the sibling get_lldp_neighbors_detail, though the summary/detail split is inferable from naming.

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 at all: nothing says when to prefer this over get_lldp_neighbors_detail, get_interfaces, or get_mac_address_table, and no prerequisites or exclusions are stated. The only routing signal is the implicit 'summary' framing of the return fields.

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

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

Annotations already declare readOnlyHint=true and the '[READ]' tag reinforces it. The description adds value beyond annotations by disclosing the returned field set (chassis id, system name/description, capabilities), but omits behavior around the optional target (what happens when omitted) and error/empty-result handling.

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?

Compact and front-loaded: the purpose sentence comes first, followed by a terse args note. No filler, though the args block is boilerplate-thin.

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

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

For a single-optional-param read tool with no output schema, the description is mostly adequate: annotations cover safety and the return fields are listed. It falls short by not explaining behavior when target is omitted (default null), which an agent needs to invoke it correctly.

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

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

Schema description coverage is 0% (the only param 'target' has no schema description), so the description must compensate; it does minimally by explaining target is a 'Device name from config.' That meaningfully identifies the expected value, though it doesn't clarify the nullable default or omission behavior.

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 (detailed LLDP neighbors) and enumerates the extra fields it returns (chassis id, system name/description, capabilities), which implicitly distinguishes it from the bare get_lldp_neighbors sibling. It never names that sibling explicitly, so the differentiation is inferable rather than stated.

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

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

There is no when-to-use guidance and no mention of get_lldp_neighbors as the alternative. The word 'Detailed' hints at a use case but the agent is left to infer when this is preferable over the basic variant.

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?

readOnlyHint=true already establishes the safety profile, and the '[READ]' prefix largely restates it. The description does add value in the absence of an output schema by naming the returned fields (MAC, interface, VLAN, flags), but it says nothing about whether entries are scoped to one device or aggregated, how large the table can be, or how to interpret static vs active.

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

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

Very short and front-loaded, with the read-only marker and returned fields in the first clause and the argument documented on its own line. No filler, though the 'Args:' block for a single parameter is slightly formulaic for the amount of content.

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

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

For a simple read-only getter with one optional parameter this is close to adequate, and the field list compensates for the missing output schema. The unresolved question of what an omitted target returns is the main shortfall.

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 the single parameter, so the description is the only source: it identifies 'target' as a device name sourced from config, which is genuinely useful. It does not explain the null default, i.e. what happens when target is omitted, leaving a meaningful 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 ([READ]) and resource (MAC address table) and enumerates the returned columns (MAC, interface, VLAN, static/active flags), so the agent immediately knows what it gets. It does not explicitly distinguish itself from the closely related get_arp_table or get_vlans siblings, which is the only thing keeping it from 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 when-to-use guidance, no statement of prerequisites or which other tools to prefer. The only usage-adjacent line ('Device name from config') describes the parameter rather than the situation that calls for this tool.

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

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

The readOnlyHint annotation already establishes the safety profile, and the "[READ]" tag redundantly repeats it. The description does add value by listing the returned attributes (name, type, state, member interfaces), which matters because there is no output schema. It says nothing about error behavior, empty results, or pagination.

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 resource and returned fields, then a compact single-argument block. No wasted prose. The "[READ]" prefix and the Args header are mildly redundant against structured fields but not excessive.

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

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

For a single-param read tool with no output schema, listing the return fields is genuinely helpful and mostly sufficient. Missing is the behavior of the optional default target (local device vs. required input), which an agent needs 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%, so the description must carry the parameter burden: "target: Device name from config" meaningfully explains the otherwise opaque "Target" property. However, the parameter is optional (default null) and the description never states what happens when it is omitted, leaving a real 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 resource with a clear read verb marker: "[READ] Network instances (VRFs)" and enumerates returned fields (name, type, state, member interfaces). This distinguishes it from siblings like get_vlans or get_interfaces by resource. It stops short of naming any sibling it replaces or contrasts with, so no explicit 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?

No when-to-use or when-not-to-use guidance is given. The only hint is the "[READ]" tag, which merely restates the readOnly annotation. An agent gets no condition for preferring this over, say, get_interfaces or get_vlans.

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

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

The readOnlyHint annotation already declares this as a safe read. The description adds that the data is 'configured' NTP servers, which distinguishes it from operational stats (e.g., get_ntp_stats), but provides no further behavioral details such as return format or target-omission 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?

The description is very brief and front-loads the key information ([READ] Configured NTP servers) before listing the argument. Every sentence earns its place with no redundancy.

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

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

For a simple read tool with one optional parameter and no output schema, the description covers the purpose and parameter meaning adequately. It could better state that the target is optional and what the return contains, but the essentials are present.

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

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

Schema description coverage is 0%, so the description carries the burden. It defines the single parameter 'target' as 'Device name from config,' which adds clear meaning beyond the schema. It does not clarify that the parameter is optional or what happens when omitted, but the core semantics are covered.

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

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

The description states a clear resource: configured NTP servers, and the [READ] tag signals the operation type. It is specific enough to distinguish from most siblings, but does not explicitly differentiate from the close sibling get_ntp_stats.

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

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

No guidance is provided on when to use this tool versus alternatives like get_ntp_stats. The description only states what it retrieves, leaving the agent to infer usage context.

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

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

The readOnlyHint annotation already establishes the safe-read profile, so the '[READ]' prefix adds little. What the description does contribute beyond the annotation is the list of returned metrics (stratum, offset, jitter, reachability), which compensates somewhat for the absent output schema. It says nothing about auth requirements, cost, or behavior when target is omitted.

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

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

Very short and front-loaded: the capability and returned fields come first. The 'Args:' block for a single parameter is slightly ceremonial given the schema already declares it, but nothing 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?

With no output schema, the description wisely lists the metrics returned, and read-only annotations cover the safety dimension. The gaps are the semantics of the optional target (null default behavior) and any indication of scope or failure modes, which leaves the agent guessing on the one input it can supply.

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 only one parameter, so the description must carry the load. 'target: Device name from config' does add meaning beyond the bare schema property named 'Target' with no description. However, it leaves the important default null unexplained — an agent cannot tell what happens if target is omitted, which matters for an optional parameter.

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

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

The description states a specific verb and resource — NTP peer synchronization stats — and even enumerates the returned metrics (stratum, offset, jitter, reachability). This is clearly distinguishable from the sibling get_ntp_servers, which is about configured servers rather than peer sync state. It stops short of explicitly naming that sibling, so 4 rather than 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 when-to-use or when-not-to-use guidance, and no alternative tool is mentioned. The only hint is the '[READ]' marker, which implies a diagnostic read but does not say in what situation an agent should reach for this over device_health or get_ntp_servers.

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?

readOnlyHint=true already tells the agent this is a safe read, and the '[READ]' prefix merely restates that annotation. The description does add value by naming the returned measurements (rx/tx power, bias) and the per-interface/channel granularity, but says nothing about behavior on interfaces without optics, error handling, or output shape.

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

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

Two short, front-loaded lines with zero filler; the resource and returned fields come before the argument block. The 'Args:' section is efficient, though the bare framing gives it a slightly terse, note-like feel.

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

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

For a single-optional-parameter read tool with no output schema, the description covers the essentials. It omits what an omitted target does and gives no hint of the return structure or volume, which leaves a real gap given the 0% schema coverage.

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: 'Device name from config' clarifies the value's source and format. It never explains the null default (does omitting target query all devices?), which is the one ambiguity an agent would actually hit.

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 resource (optical transceiver levels) plus the specific measurements returned (rx/tx power, bias) and the granularity (per interface/channel). No sibling covers optics, so differentiation is effectively automatic, though the description never says so 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?

There is no when-to-use guidance, no prerequisites, and no pointer to any alternative tool. The agent must infer from the name that this is a diagnostics read used to check transceiver health; nothing in the text states the triggering condition.

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

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

Annotations already declare readOnlyHint=true, so safety is covered structurally; the description redundantly reinforces it with '[READ]' and adds the useful detail that protocol filtering is optional. It does not disclose output shape, hit/miss behavior for an unknown prefix, or whether results are live vs cached.

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 one-line summary followed by a tight Args block; every line earns its place and there is no filler. The bracketed '[READ]' tag is slightly redundant with the annotation 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?

No output schema exists, and the description gives no indication of what a lookup returns (matched route, next-hop, protocol, empty result handling). For a read tool whose annotations cover safety, this is adequate but leaves the agent guessing about result shape.

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 carries full burden and does document all three parameters with examples ('10.0.0.0/24', 'bgp, ospf, static') and the meaning of target ('Device name from config'). It does not clarify that target is optional (defaults to null) or what happens when protocol is left empty.

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 ('Routing-table lookup') plus the scoping input ('for a destination prefix'), which is unambiguous. No sibling performs routing lookups, so there is no ambiguity to disambiguate against the listed tools; it stops just short of 5 only because it does not frame itself relative to any 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?

Usage is implied by the subject matter — an agent with a destination prefix knows this is the tool — but there is no explicit when-to-use/when-not guidance and no named alternative. Given no sibling overlaps routing lookups, the omission is low-cost but still leaves usage to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds a genuinely useful, non-obvious behavioral fact — that community strings are redacted in the output — plus the field-level contents, which goes beyond what the annotation provides.

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

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

Front-loaded with the key fact (what it returns and the redaction), then a compact Args block. Short and mostly waste-free, though the Args section is minimal enough that it barely earns its lines.

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

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

For a simple single-parameter read tool with no output schema, the description adequately conveys the data returned and a key privacy behavior. The only gap is the semantics of the optional target default, which is minor for this tool's complexity.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does clarify that 'target' is a device name from config. However, it says nothing about what happens when target is omitted (the schema shows a default of null) or accepted formats.

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 resource (SNMP metadata) and enumerates the fields returned (chassis id, contact, location), which distinguishes it from the many sibling get_* tools that retrieve other device data. The verb is carried by the tool name rather than the description, but the scope 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?

There is no statement of when to use this tool versus alternatives such as device_facts or get_environment, nor any exclusions or prerequisites. The '[READ]' tag hints at read-only context but doesn't route the agent among siblings.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful output context by stating 'Password hashes are NOT returned,' but it does not cover permissions, error behavior, or output structure beyond that exclusion.

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, front-loaded with the read marker and key exclusion, then documents the argument. Every sentence contributes to correct invocation with 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 simple one-parameter getter with no output schema, the description identifies the returned resources and an important exclusion. It is nearly complete but leaves unclear what happens if target is omitted and does not describe the shape of returned user/privilege data.

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 does so for the sole parameter by defining target as 'Device name from config,' though it does not clarify the optional/default-null behavior.

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

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

The description clearly states the resource and scope: 'Local users and privilege levels' for a read operation. It does not explicitly distinguish this tool from the many sibling get_* tools, but the resource is specific enough for an agent to identify it.

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 or when-not-to-use guidance is given. The description only implies a read operation via '[READ]' and does not explain how this differs from alternatives such as device_facts or get_snmp_information.

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?

readOnlyHint=true already declares the safety profile, and '[READ]' merely restates it. The one genuine addition is '(driver support varies)', which warns the agent that output completeness depends on the platform driver — a useful behavioral caveat not present in annotations, though error/auth behavior remains 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?

Front-loaded and compact: the resource and return shape come first, arguments second. The '[READ]' prefix is redundant with the annotation but costs only a few tokens, so the structure is efficient.

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

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

For a simple one-parameter read with annotations covering safety, the description covers purpose, return fields, and a driver caveat. With no output schema the field list does real work, though null-target behavior and error cases are left implicit.

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 load; 'target: Device name from config' does supply the meaning and provenance of the single parameter, which the schema lacks. However, it omits that target is optional (default null) and what happens if it is omitted, leaving partial 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?

States a clear verb+resource (retrieve VLANs) and even enumerates the returned fields (id, name, member interfaces), which is more specific than most siblings. It does not explicitly distinguish itself from adjacent tools like get_interfaces or get_mac_address_table, so it stops short of full 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternative tools. The presence of 'target' implies a device-scoped read, but nothing tells the agent when to prefer this over the other get_* 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?

readOnlyHint=true already covers the safety profile, but the description adds real behavioral detail: it names the two upstream calls it makes, describes the output ordering (worst-first), and states each finding cites the measured number with a cause and concrete action. That is meaningful disclosure about what the tool does and returns 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?

Front-loaded with the [READ] tag and a one-line purpose, then the mechanism, then the single arg. Every sentence earns its place with 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?

With no output schema, the description steps in by describing the report shape (worst-first findings, cited measurements, cause, action), so an agent knows what to expect. Still no mention of pagination or scoping limits, but for a single-param read diagnostic it is largely complete.

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

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

Schema coverage is 0%, so the description must carry the parameter. It does: 'target: Device name from config; omit to use the default device' explains both the value source and the optional-default behavior, which the bare anyOf[string, null] schema does not convey.

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 'Flag' and the resource 'interfaces' are specific, and the qualifying conditions (admin-up/oper-down, erroring, discarding, flapping) pin down exactly what it detects. It is clearly distinguishable from the sibling get_interfaces and get_interfaces_counters that it consumes as inputs.

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?

By stating it 'pulls get_interfaces + get_interfaces_counters,' it implicitly positions itself as the diagnostic layer above those raw readers. However, it never explicitly says 'use this instead of get_interfaces_counters when you want interpreted findings,' so the when/when-not routing 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?

readOnlyHint=true is already in annotations, so the safety profile is free; the description instead adds non-obvious behavior — the exact return envelope, the truncation flag, and the operational caveat that truncated results invalidate drift analysis. It stops short of describing auth requirements or pagination beyond the limit knob, so 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?

Front-loaded with a [READ] tag, purpose, differentiation, return shape, and caveat in a handful of tight lines. Every sentence carries actionable information; 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?

With no output schema, the description supplies the full return contract ({interfaces, returned, limit, truncated}) plus the crucial truncation caveat, and documents both parameters. There is no gap an agent would need to guess at before calling this tool.

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

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

Schema coverage is 0%, so the description must compensate, and it does: 'device' is pinned as an exact NetBox name with a pointer to netbox_list_devices, and 'limit' is explained as a max count with its default. It doesn't clarify whether limit is an offset-style pagination or a cap on a single page, hence 4 rather than 5.

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

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

States a specific verb and resource ('List a NetBox device's interfaces') plus the fields returned, and explicitly distinguishes the source-of-truth inventory from the live-state sibling get_interfaces. An agent can route between the two without opening either schema.

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

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

Names the exact use case (drift comparison against get_interfaces), points to netbox_list_devices for device discovery, and gives an explicit when-not rule: do not report drift from a truncated list, re-run with a higher limit. This is genuine routing guidance, not implied context.

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

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

readOnlyHint=true already declares the safe-read profile, so the '[READ]' tag is redundant. It does add one behavioral fact beyond annotations — matching is by EXACT name, so no fuzzy/partial lookup — but says nothing about error behavior for a missing device.

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

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

Extremely tight: a one-line purpose sentence plus a single arg note, with the READ marker and core purpose front-loaded. Nothing 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 one-parameter read-only lookup this is close to adequate, but with no output schema the description never indicates what the returned device contains, and it omits failure behavior when the exact name does not match.

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 semantics. It does tell the agent the value must be an exact device name and points to netbox_list_devices as the source of valid values, which is meaningful beyond the bare string type. Format/case conventions are still unspecified.

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 ('Return') and resource ('a single NetBox device') with the exact-name scope. It points at netbox_list_devices, which implicitly distinguishes this single-record lookup from the list variant, though it never states the distinction 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 parenthetical '(see netbox_list_devices)' hints at where to obtain the name and implies this tool is for when you already have one. There is no explicit when-to-use/when-not-to-use statement or stated precondition (device must 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?

readOnlyHint already covers the safety profile, so the description's added value is meaningful: it discloses the prerequisite ('Requires a configured NetBox block'), the exact return envelope, and the truncation behavior with an actionable remedy. Pagination offset/cursor behavior is not covered, keeping it at 4.

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

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

Front-loads the action and scope, then follows with prerequisite, usage, return shape, and args in a scannable order. Slightly verbose (the truncation warning spans two sentences) but every sentence carries operational value.

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

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

With no output schema, the description supplies the return shape and truncation semantics, which is exactly what an agent needs to avoid false conclusions about coverage. It omits guidance on how to page beyond raising 'limit' and does not route to sibling tools for drill-down.

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 load, and it does: 'name' is explained as a contains match (real semantics beyond the bare string type) and 'limit' gets a stated default. Minor gap: no mention of whether name matching is case-sensitive or how limit interacts with the truncation threshold.

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

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

States a specific verb and resource ('List NetBox devices') and enumerates the returned fields (name, role, site, status, primary IP). The [READ] prefix plus 'List' cleanly distinguishes it from the sibling netbox_get_device, which fetches a single device.

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

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

Explicitly states the use case: 'confirm intended state before pushing config to a device,' which ties it into the config_* workflow siblings. It does not name an explicit alternative or exclusion (e.g., when to prefer netbox_get_device), so it stops short of a 5.

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

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

Goes well beyond the annotations by disclosing that the inverse runs through its own governed tool with its risk tier recorded in that tool's audit row, that dry_run previews without executing, and that a token is single-use. The single-use constraint and the governed-inverse mechanism are non-obvious behaviors an agent must know and are not captured by destructiveHint/idempotentHint.

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 tag and core verb, then an Args block for each parameter. Every sentence carries distinct information with no filler or repetition.

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

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

For a destructive write tool with no output schema and 0% schema coverage, the definition covers the operation, safety mechanism, preview path, and all parameters. It doesn't state the success/return shape, but an agent has enough to invoke it safely and correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: undo_id is explained with its origin, dry_run is defined as a non-executing preview, and target is described as a pass-through to the inverse tool. Target's semantics remain somewhat vague ('when it accepts a target'), keeping it short of a 5.

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 ('Apply a recorded undo by dispatching its inverse tool') and distinguishes itself from the sibling undo_list by explaining that undo_id comes from undo_list or a write result. The [WRITE][risk=medium] tag reinforces the operation class. It stops short of an explicit 'unlike undo_list which only lists' contrast, so a 4 rather than 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?

Gives clear operating context: use dry_run=True to preview, the undo_id source is named, and it warns the token can only be applied once. There's no explicit when-not-to-use or named alternative for applying undos, but the intended usage is unambiguous.

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

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

Annotations only supply readOnlyHint=true; the description goes well beyond that by disclosing the return shape, that truncation is *measured* via an extra-row fetch, and that effectVerified=false means the reversed change is only PROBABLE, with a caution to check live state and not over-report. This is meaningful operational context the annotations cannot carry.

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 purpose and the sibling handoff, then structured paragraphs for return value and the effectVerified caveat. Every sentence carries information, though the emphasis on truncation being 'measured, not guessed from a length coincidence' is slightly verbose for the value it adds.

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

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

With no output schema present, the description supplies the return JSON shape, the meaning of every field an agent must act on (returned, limit, truncated, effectVerified), and the follow-up behavior for truncation. Nothing needed to call or interpret it correctly is missing.

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

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

Schema description coverage is 0% and no param has an enum, so the description must compensate, and it does fully: limit is documented as default 50 / capped at 500, and target is documented as ignored with the reason (host-local undo state, kept for CLI uniformity).

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

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

States a specific verb and resource ('List recorded, not-yet-applied undo tokens') plus ordering ('most recent first'). The [READ] tag and the reference to undo_apply make it clearly distinguishable from the sibling that actually applies tokens.

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

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

Explicitly routes the agent: 'Use the undoId with undo_apply.' and tells it to re-run with a higher limit when truncated rather than reporting a partial list as complete. It lacks an explicit 'when not to use this' condition, so it falls just short of a 5.

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