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

Annotations already declare non-read-only, non-idempotent, destructive; the description adds meaningful context beyond them — reversibility via undo, the fact that prior entries are captured, the medium risk rating, and the dry_run preview path. The only mild tension is calling the operation 'reversible' while destructiveHint=true, but appending an entry to a list is genuinely a mutation, so this reads as nuance rather than contradiction.

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

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

Front-loaded tags give the safety and risk profile before any prose, followed by two short sentences on reversibility and preview. The Args block is compact and each line carries information not present in the schema titles.

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

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

For a mutation tool with no output schema, the description covers mutation semantics, reversibility, undo path, dry-run preview, and every parameter. It is close to self-sufficient; only target resolution details and any post-write verification step are absent.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it documents all four parameters: name (with its source tool), entry, dry_run, and target (including the omit-for-default behavior). The compensation is solid, though entry's description is brief and target could say more about where config values come from.

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 — add one entry to an alias — and qualifies it with [WRITE][risk=medium], which orients the agent immediately. It implicitly distinguishes itself from remove_alias_entry through the 'add one entry' framing, though it never names that sibling 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?

It gives concrete operational context: capture of prior entries before the change, dry_run=True for preview, and it points to list_aliases as the source of valid names, which is a real routing hint. There is no explicit when-not guidance, but the preview and undo paths cover the main decision points.

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, and the '[READ]' tag largely repeats it. The description does add one genuinely useful behavioral detail: target should be omitted to fall back to the default target. It says nothing about return shape, entry format, or whether results are paginated, so it adds only modest context 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?

A one-line purpose followed by two tight parameter lines; the scope-defining content ('member entries of one alias') is front-loaded and nothing is padded.

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

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

For a two-parameter read-only tool with annotations covering safety and no output schema, the description covers purpose, both parameters, and the default-target fallback. The one remaining gap is that it never hints at what an entry record contains beyond the hosts/networks/ports categories.

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 does so: it defines 'name' as an alias name sourced from list_aliases and defines 'target' as a firewall target name from config with the default-omission behavior. Only the exact expected string format of these values is left implicit.

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: it returns the member entries (hosts/networks/ports) of a single alias, which is more specific than a bare 'get alias'. It is implicitly distinguished from list_aliases, add_alias_entry and remove_alias_entry by scoping to one alias's members, though no sibling is named as an explicit alternative.

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

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

The '[READ]' prefix and the note that 'name' comes 'from list_aliases' imply the prerequisite lookup step, and 'target: omit for the default' tells the agent when to leave a parameter out. However, there is no explicit when-to-use vs when-not guidance or comparison against add_alias_entry/remove_alias_entry.

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 destructive/not-idempotent annotations: it discloses the lockout self-protection logic, the exact refuse-vs-warn boundary (alias destinations, 'any', interface groups warn), that dry_run returns the full change set and assessment, and that override should only be used with console access. This is exactly the behavioral context 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 tags and the one-line purpose, then justification, then Args. Every sentence earns its place, though dry_run is explained twice (body and Args), a minor redundancy that keeps it from a 5.

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

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

For a destructive, non-idempotent mutation tool with no output schema, the description covers purpose, safety preconditions, the preview path, and the escape hatch. Nothing an agent needs to call it safely 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% and there are 3 optional params, so the description carries full burden — and it does: dry_run's return semantics, override's meaning and audience, and target as a config name defaulting when omitted. All three params are explained with meaning beyond the bare schema.

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

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

States a specific verb and resource — commit the staged firewall config — and pins its role in the workflow as the 'make it live' step after staging via toggle_rule. An agent can tell it apart from staging siblings like toggle_rule immediately.

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

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

Clearly positions itself as the commit step following staged edits (naming toggle_rule), prescribes dry_run before every apply, and restricts override to operators with out-of-band access. It stops short of pointing at pending_changes or undo_apply as the inspection/reversal alternatives, so 4 rather than 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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description adds real value beyond that: it discloses the internal classification taxonomy (port scan, service probe/brute-force, generic) and that a recommended action is attached to every row, which an agent needs to interpret results. No auth, rate-limit, or pagination notes, 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 the [READ] marker and one-line purpose, then mechanics, then Args and Returns. Given the 0% schema coverage, the Args section is load-bearing rather than redundant. Slightly long overall, but no sentence 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 properly documents the return dict shape ({blocksEvaluated, distinctSources, topSources:[...], note}) and the per-row fields, which is exactly what the agent needs. The main residual gap is sibling-level guidance on when to prefer this over firewall_log, but otherwise it is complete for a 4-parameter read/analysis 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% — the schema provides only bare titles — so the description must carry the full burden, and it does. Each of the four parameters is documented with meaning and defaults: 'top' (rows, noisiest first, default 20), 'limit' (live rows to pull, default 500), 'log_entries' (with its field shape and that it skips the live pull), and 'target' (from config, omit for default).

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 pair (rank, classify) and resource (noisiest blocked sources), and states the exact mechanics — filtering to blocked entries, aggregating by source, and classifying cause. This is distinguishable from siblings like firewall_log or top_talkers, which neither aggregate blocked-only entries nor attach a cause/action classification.

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 operational routing: pass 'log_entries' for pure analysis, or a target to pull live. That tells the agent which mode to invoke and why. It stops short of naming alternative tools (e.g., firewall_log, rule_hit_and_shadow_analysis) or stating when this tool should be preferred over them.

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, but the description adds real behavioral context: it discloses that leases the platform did not report are surfaced via an 'onlineUnknown' bucket, which is useful given there is no output schema. It stops short of describing pagination or ordering.

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 read tag and the resource/return summary, then the two args. Efficient with no filler, though the bracketed '[READ]' prefix is slightly redundant with the readOnlyHint annotation.

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

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

For a two-param read tool with no output schema, the description covers the return fields, the online filter, the unknown-state bucket, and the target default, which is enough to call it correctly. Minor gaps remain around ordering/limits, but nothing critical is missing.

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

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

Schema description coverage is 0%, so the Args block carries the full burden and does compensate: online_only's filtering behavior and the fallback counting rule are explained, and target is defined as a config target name with 'omit for the default'. This meaningfully exceeds the bare schema, though the target string format is not specified.

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 ('Active DHCP leases') and even enumerates the returned fields (IP, MAC, hostname, state), which cleanly separates it from the static-mapping sibling dhcp_static_mappings. An agent can identify exactly what this returns 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?

The '[READ]' tag and the online_only arg imply a read-only listing use case, but there is no explicit when-to-use/when-not guidance and no named alternative among the many siblings (e.g., dhcp_static_mappings vs live leases). Usage is only implied.

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 is a safe read, so the [READ] tag is largely redundant. The description does add the useful fact that it returns MAC↔IP pairings, but says nothing about pagination, empty results, or auth requirements beyond the annotation-covered safety profile.

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 bracketed mode tag followed by the resource and a compact Args block. Every line earns its place with no filler, though the [READ] tag duplicates the annotation.

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, there is little more an agent needs: it knows it is safe, what it returns conceptually, and how the one parameter behaves. Return-shape detail is the only minor omission.

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

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

Schema coverage is 0% and the parameter has no description, so the description carries the burden here. It explains that "target" is a firewall target name from config and that omitting it selects the default, which is meaningful semantics the schema does not supply. Only the string format/valid values remain 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?

"DHCP static (reserved) mappings (MAC ↔ IP)" states a concrete resource and even hints at the returned data shape, and "static (reserved)" implicitly distinguishes it from dynamic-lease tools. It doesn't explicitly name its closest sibling dhcp_leases, so it falls short of full sibling differentiation.

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

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

The [READ] marker signals it is a read operation, but there is no statement of when to use this rather than dhcp_leases or any other DHCP/status tool, and no prerequisites or exclusions are given. Usage must be inferred from the 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?

The readOnlyHint annotation is echoed by the [READ] tag (no extra credit there), but the description goes well beyond it: it documents the exact return envelope, the meaning of 'truncated', and the corrective action of re-running with a higher limit. For a log reader with no output schema, that truncation/pagination semantics is genuinely load-bearing 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 scope line, then a compact Args block, then the return envelope. Every sentence adds information — no restatement of the tool name and 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 zero schema description coverage and no output schema, the description supplies both the parameter meanings and the response shape, including the truncation edge case. There is no material gap an agent would need to guess at before calling it.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: it enumerates the valid 'action' values (pass, block, reject, rdr, nat) that the schema leaves as an untyped string, gives the default of 200 for 'limit', and explains that 'target' comes from config and is optional. This is meaningful compensation for the schema gap.

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

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

The description states a specific verb and resource — recent firewall-log entries — plus the available filter dimension (pass/block and the wider action set). It's immediately distinguishable from analysis-oriented siblings like blocked_traffic_rca, but it never names or contrasts those siblings explicitly, which is the only thing separating 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?

Usage is implied rather than stated: an agent can infer this is the tool for raw log inspection, and the description notes that omitting 'target' uses the default. There is no explicit guidance on when to use this versus blocked_traffic_rca or top_talkers, and no when-not conditions.

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 tells the agent this is a safe read, and the '[READ]' prefix merely restates it. The description adds useful behavior (it reports update availability, not just a version string) and the default-target fallback, but says nothing about auth requirements, rate limits, or return shape for a tool with no output schema.

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

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

One sentence of purpose plus a short Args note — front-loaded, tight, and every line carries information. The '[READ]' tag is mild redundancy against readOnlyHint, but the cost is negligible.

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 essential call-time information (what it returns conceptually, how to supply or omit target) is present. The only real gap is what the returned payload looks like, which the agent must discover empirically.

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

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

Schema description coverage is 0% and the schema only carries a bare 'Target' title, so the description carries the full burden — and it does well by explaining that the value is a firewall target name from config and that omission selects the default target. It stops short of giving format examples or listing valid target names.

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 resource (firmware/OS version) and outcome (whether updates are available), which is specific enough to distinguish it from status siblings like health_status or interface_status. It does not explicitly name those siblings, but the resource is unambiguous.

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

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

Usage is only implied by the tool's nature — an agent can infer it should call this when firmware/OS version or update availability is needed. There is no explicit when/when-not, no prerequisites, and no mention of alternative status tools (health_status, interface_status) for adjacent questions.

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; the description goes further by disclosing the threshold defaults (5% loss, 150ms RTT), the live-pull-vs-injected-rows behavior, and the fact that rankings carry raw numbers rather than a black-box verdict. It does not mention rate limits or auth requirements, so it isn't exhaustive.

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 core operation and its [READ] tag, then layers behavior, args, and returns in an easy-to-scan structure. Slightly long with minor redundancy between the opening line and the follow-up paragraph, but every section earns its place.

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

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

There is no output schema, so the description's return-value documentation (gatewaysEvaluated, downCount, degradedCount, thresholds, worst[] with cause/action) is essential and present. All four parameters are explained and the read-only nature is clear, leaving nothing an agent needs missing.

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

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

Schema description coverage is 0%, so the description carries the burden, and it largely does: it defines loss_pct and latency_ms as degradation thresholds with defaults, spells out the shape of injected 'gateways' rows ({name, address, status, lossPercent, rttMs}), and describes 'target' as a config firewall name. That's substantially more meaning than the bare schema types 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?

Opens with a specific verb+resource (rank gateways by loss+latency) plus the distinctive RCA behavior (map each down/degraded gateway to cause + action). This clearly separates it from the raw-status sibling 'gateway_status' without needing to name it, since ranking and root-cause attribution are the differentiating actions.

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

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

Explicitly tells the agent the two usage modes: pass 'gateways' for pure analysis of injected rows, or a target for a live pull. That's clear context, but it names no alternatives or exclusions (e.g., 'for raw status without RCA, use gateway_status'), so it stops short of full 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?

The readOnlyHint annotation already establishes the safe-read profile, so the '[READ]' prefix adds nothing beyond it. The description does earn some credit by disclosing the returned signals (status, loss %, RTT latency), which matters because there is no output schema. It says nothing about polling cost, caching, or failure 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?

Very short and front-loaded: the resource and returned fields come first, then the args. Every sentence earns its place. The '[READ]' tag is mildly redundant with the annotation but is cheap and conventional.

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-optional-parameter read tool with no output schema, the description supplies the essentials: what is measured and how to scope it by target. Missing only edge-case behavior (unknown target, unreachable gateway) and any note on interpreting loss/RTT values.

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 full burden, and it does explain the single parameter: a firewall target name sourced from config, with omission falling back to the default. That is meaningfully more than the schema's bare anyOf/string typing, though it doesn't clarify valid name forms or whether 'default' is a configured target.

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

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

Names the resource (WAN/LAN gateways) and the specific data returned (status, loss %, RTT latency), which is more concrete than most of its *_status siblings. It does not explicitly distinguish itself from gateway_health_rca or health_status, so it stops short of a 5.

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

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

There is no statement of when to call this versus gateway_health_rca, health_status, or interface_status — the sibling set makes that ambiguity meaningful. The only usage-like text is the parameter note about omitting target for the default, which is invocation help, not tool selection 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 '[READ]' tag is largely redundant with that. The real added value is the enumeration of returned fields, which substitutes for the absent output schema and tells the agent what a snapshot contains. No auth or rate-limit context is given, 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?

Two compact lines, capability statement front-loaded before the argument note, 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 single-parameter, read-only snapshot tool with no output schema, the description covers purpose, returned data, and the one argument, which is essentially everything an agent needs. Slight incompleteness around valid target values keeps it from a 5.

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: 'target: Firewall target name from config; omit for the default' explains both meaning and the optional/null default behavior. It still doesn't say where valid target names come from, so not 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 ('System health snapshot') and enumerates what it covers (hostname, uptime, CPU, memory, load), which is enough to distinguish it from narrower siblings like interface_status or firmware_status without opening a schema. It does not explicitly name those siblings, so it falls short of a 5.

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

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

There is no statement of when to use this versus the many sibling status tools (firmware_status, gateway_status, interface_status). The only usage-like guidance is the parameter note about omitting target for the default, which is param guidance rather than tool selection 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?

The [READ] tag and readOnlyHint=true are consistent, so no contradiction. However, with annotations covering only the read safety profile, the description adds little else: no statement about ordering beyond 'down interfaces first', no mention of scope (all interfaces?), rate limits, or auth requirements.

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

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

Front-loads the [READ] marker and purpose, then lists the single argument in a compact Args block. No wasted words, though the formatting resembles a docstring rather than an agent-facing instruction.

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 covers the essentials of what it returns and one argument. It does not explain the default target behavior beyond a phrase, nor any pagination/filtering, leaving some gaps for multi-target environments.

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 'target' has only a title and default, so the description must compensate. It does briefly — 'Firewall target name from config; omit for the default' — but does not specify format or where 'config' draws the name from.

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 ('Interfaces with link status + address'), which is more informative than a bare tautology. It doesn't explicitly differentiate from siblings like gateway_status or health_status, but the resource is distinct enough to be selectable.

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

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

No guidance on when to use this vs alternatives such as gateway_status, health_status, or firmware_status. The phrase 'target: Firewall target name from config' hints at multi-target usage but does not establish selection criteria or exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that results include phase-1/phase-2 SAs and their state, which is useful return-shape context, but says nothing about scope (all tunnels? all targets?), volume, or whether peers are contacted live.

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 tight summary line plus a single documented arg, front-loaded and free of filler. The '[READ]' tag is mildly redundant with readOnlyHint but serves as a fast scan marker in a 34-tool set.

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

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

For a zero-required-parameter read tool with no output schema and annotations covering the safety profile, the description supplies the essential missing pieces: what is returned (phase-1/phase-2 SAs with state) and how target selects the device. Only minor gaps remain around scope and 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 coverage is 0% and the parameter has no schema description, so the description must carry it — and it does: 'Firewall target name from config; omit for the default' explains both provenance of the value and the default/omission behavior for the single optional param.

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 ('IPsec security associations (phase-1/phase-2)') and an implicit list/retrieve verb with the returned attribute ('with state'). It is recognizably distinct from the other VPN-related siblings (wireguard_status, openvpn_sessions), but it never explicitly contrasts itself with them, so it lands at clear-but-not-routing.

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]' prefix signals this is a non-mutating inspection call, which implies its usage context, but there is no explicit when/when-not guidance and no alternative (e.g. wireguard_status, openvpn_sessions) is named. Usage must be inferred from the tool name and the toolset.

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 (readOnlyHint=false, destructiveHint=true, idempotentHint=false) by disclosing the self-referential failure mode: the flush also kills this tool's own connection, so the call may look like it failed when it actually succeeded, and a blind retry is the wrong reaction. It also reassures that access is not lost because the permitting rule is untouched — exactly the kind of context an agent cannot get 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?

Front-loads the critical [WRITE][risk=medium] tag and the core action, then devotes a short paragraph to the counterintuitive failure behavior, then the args. No sentence is filler; the ordering matches what an agent needs to decide whether to call.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers effect, side effects, failure semantics, safety of access, preview capability, and every parameter. An agent has everything needed to invoke it correctly and interpret an ambiguous result.

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 documents all three parameters: filter_ip as an optional source IP (blank = all states), dry_run as preview-only, and target as a firewall name from config with a stated default. Meaning is added beyond the bare property titles.

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

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

States a specific verb and resource: 'Flush pf state-table entries (optionally one source IP).' This is clearly distinguishable from read-oriented siblings such as states_table or rule_states, and the parenthetical scope qualifier removes ambiguity about breadth.

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 supplies clear operational context ('Drops tracked connections; they re-establish on the next packet') and directs the agent to 'Pass dry_run=True to preview', which is actionable guidance. It stops short of explicitly naming the alternative (e.g., inspect via states_table first) or stating when-not to use it, so it falls just below the top tier.

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 read-only safety profile, so the '[READ]' prefix is largely redundant. The description adds that aliases carry a member count and that target selection is config-driven, but discloses nothing about result size, pagination, or filtering behavior.

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

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

Two short lines, front-loaded with the essential purpose and the returned fields, followed by arg guidance. No filler, though the bracketed '[READ]' tag is arguably padding given the annotations.

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

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

For a read-only, no-output-schema list tool with one optional parameter, the description covers the resource, the returned fields, and the parameter's origin and default. An agent has enough to call it correctly; only result volume/ordering is unaddressed.

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

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

Schema description coverage is 0%, so the description must compensate for the single 'target' parameter — and it does, explaining it is a firewall target name taken from config and that omitting it selects the default. Only the null-vs-string handling is left to the schema.

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

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

States a specific verb+resource ('All firewall aliases') and enumerates the returned fields (name, type, description, member count), which lets an agent distinguish it from siblings like add_alias_entry or alias_entries. It stops short of explicitly naming the closest alternative (alias_entries), so it is clear but not fully differentiated.

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 rather than stated: it reads as a bulk listing of alias objects, and the only guidance given is that 'target' can be omitted for the default. There is no explicit when-to-use vs. alias_entries or rule-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 establishes the safety profile, and the '[READ]' tag merely restates it. The one piece of added context is 'normalized', which hints the output is transformed, but the description never explains what normalization means or whether results are paginated or truncated.

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

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

The definition is front-loaded with the action and scope in one line, followed by a compact Args block. Nothing is padded, though the '[READ]' tag is redundant given the annotation.

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, two-optional-parameter listing tool with no output schema, the description covers the operation and both arguments adequately. The gaps (meaning of 'normalized', default target value, result size limits) are minor rather than call-blocking.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does so reasonably: 'interface' is explained as an optional filter with concrete examples (wan, lan), and 'target' is described as a config name that defaults when omitted. It stops short of naming the actual default value or listing valid interfaces.

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

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

The description gives a specific verb+resource ('List filter rules') plus scope ('optionally on one interface') and a behavioral qualifier ('normalized'). It implicitly separates itself from siblings like rule_detail and rule_stats by being a listing operation, but never names those alternatives, so differentiation is left to inference.

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: the agent can infer this is the enumeration counterpart to rule_detail/rule_states/rule_stats, but the description never says when to reach for list_rules versus those tools. No prerequisites, exclusions, or alternative routing are provided.

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

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

readOnlyHint=true already establishes the safety profile, and the [READ] tag aligns with it. The description adds that output is normalized and the mapping is external↔internal, but says nothing about return structure, pagination, or how many entries to expect.

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 read tag and resource in one line, then documents the argument compactly. No filler, though the Args block styling is slightly verbose for a single 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?

For a simple read-only tool the description covers purpose and the single parameter, but with no output schema it should say more about the returned shape of the mapping list. The 'normalized' hint is the only return-value context provided.

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 undocumented in the schema, so the description carries the full burden and does so: 'Firewall target name from config; omit for the default' explains both meaning and 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?

States a specific verb ([READ]) and resource (1:1 NAT mappings), with scope qualifiers (external ↔ internal, normalized) that distinguish it from sibling NAT tools like nat_port_forwards and nat_outbound. It does not name those siblings explicitly, 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?

No when-to-use, when-not, or alternative selection guidance is given. The reader must infer that this is for 1:1 NAT specifically versus port-forward or outbound NAT from the name alone. The only practical guidance ('omit for the default') is parameter-level, not usage-level.

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]' prefix merely restates that. The one piece of added context is 'normalized,' which hints at how results are shaped, but nothing is said about scope (all mappings?), paging, or empty results.

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

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

Two short blocks with the purpose front-loaded and the argument documented immediately after; nothing is padded. The 'Args:' block is slightly heavier than needed for one parameter but remains 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 single-parameter read-only listing tool with no output schema, the description covers purpose, safety by inference, and the one argument. Only the absence of any sibling routing or result-shape detail keeps it short of full completeness.

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

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

Schema coverage is 0% and 'target' is completely undocumented in the schema, so the description carries the full burden: it defines the value as a firewall target name from config and states the default behavior when omitted. That is meaningful compensation for a 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?

States a specific verb ([READ]) and resource (outbound/source NAT mappings), which is enough to separate it from the destination-NAT siblings nat_port_forwards and nat_one_to_one. It does not explicitly name those siblings, so differentiation is inferential 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 alternatives among the many sibling status/list tools. The only usage hint, 'omit for the default,' applies to the argument rather than to tool selection.

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

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

readOnlyHint already declares a safe read, so the bar is lower. The description adds that rules are 'normalized' and that target comes from config, but says nothing about auth, pagination, or output behavior.

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

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

Two short lines with no filler, front-loaded with [READ] and the resource. The Args section is minimal and directly useful.

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 tool with readOnlyHint and no output schema, the description gives enough to invoke it correctly. 'Normalized' is vague and no return structure is described, but no output schema exists to require it.

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

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

Schema coverage is 0% – the target parameter has no description in the schema. The description compensates by explaining it is a firewall target name from config and that omitting it uses the default, covering the essential semantics.

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

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

[READ] marks the operation and 'Inbound port-forward (DNAT) rules' names the resource precisely, implicitly distinguishing it from nat_outbound and nat_one_to_one. Lacks an explicit verb like 'list,' but the tag and resource are specific enough for selection.

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

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

The only guidance is for the target argument ('omit for the default'); there is no explicit when-to-use or when-to-choose-this-over-nat_outbound/nat_one_to_one. Usage is implied by the purpose and resource scope.

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 that the result contains session client details (name, address, bytes), which is useful since there is no output schema, but it says nothing about pagination, session limits, or auth requirements beyond the read nature.

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

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

Two short lines, front-loaded with the what and followed by the parameter note; nothing is wasted. The 'Args:' block is slightly boilerplate for a single parameter but harmless.

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, annotated, single-parameter read tool with no output schema, the description covers purpose, the parameter, and a sketch of the return fields. The only unmet need is routing guidance relative to the many sibling status tools.

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

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

Schema description coverage is 0%, so the description carries the burden: it explains that 'target' is a firewall target name from config and that omitting it selects the default. That is exactly the missing semantic for this optional parameter, though it does not clarify format or valid values.

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

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

The description names the specific resource (OpenVPN sessions / connected clients) and even previews the returned fields (name, address, bytes), with a [READ] tag marking the operation type. It is clearly distinguishable from siblings like wireguard_status and ipsec_sas, though it uses a noun phrase rather than an explicit verb.

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

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

There is no guidance on when to use this tool versus alternatives such as wireguard_status or ipsec_sas, nor any prerequisites or exclusions. The only contextual note ('omit for the default') is a parameter detail, not usage guidance.

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

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

Annotations only grant readOnlyHint=true, but the description adds substantial behavior: what constitutes lockout risk (disabled pass rule / enabled block rule over the management path), worst-first ranking, the `certain` flag semantics, and what blocks vs warns. It also clarifies that `basis` reports staged STATE, not a diff — a non-obvious behavioral detail no structured field carries.

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 [READ] tag, then usage, then behavioral detail, then args — a sensible ordering. Every section adds information, though the prose is denser than strictly necessary; the `basis` paragraph earns its place by preventing a state/diff misread.

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

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

With no output schema and a single optional param, the description still describes what is returned (ranked findings, certain flag, basis semantics) and the gating relationship to apply_changes. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry the param, and it does: 'target: Firewall target name from config; omit for the default.' This explains both the meaning and default behavior. It stops short of format examples, but for a single optional string it is adequate.

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: it reads the staged rule set that apply_changes would commit, specifically surfacing lockout risk. It is clearly distinguished from apply_changes (which commits) and from state-inspection siblings, and the [READ] tag disambiguates intent.

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

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

Explicit routing: 'Run this BEFORE apply_changes,' which directly names the sibling it gates. It also describes the consequence of each finding class (certain ones make apply_changes refuse, uncertain ones warn only), giving the agent a clear decision model for when this tool matters.

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, so the safety profile is partly covered. The description adds genuinely new information beyond that: 'IRREVERSIBLE — audit only, no undo' quantifies the blast radius and warns there is no rollback path, which is the key decision input for an agent contemplating a destructive action.

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?

Risk and irreversibility are front-loaded in the first line, followed by the practical dry_run tip. There is minor redundancy — dry_run is explained once inline and again in the Args block — but nothing is padded or buried.

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

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

For a two-parameter, no-output-schema destructive tool with annotations already covering safe/unsafe flags, the description covers the essentials: risk, irreversibility, preview path, and target default. Missing only the discovery mechanism for valid targets and any permission/auth prerequisites.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does document both parameters: dry_run's preview behavior and target's meaning plus the 'omit for the default' behavior. It stops short of explaining valid target values ('name from config' is not a formal enumeration), leaving some ambiguity about how to discover a valid target.

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 ('Reboot') and resource ('the firewall') in the first two words, and the [WRITE][risk=high] prefix immediately separates it from read-oriented siblings like health_status. It is clearly distinguishable from the similarly named restart_service because the resource is named.

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

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

Gives strong context: high-risk write, irreversible, and the concrete workaround 'Pass dry_run=True to preview', which tells the agent how to proceed safely. It does not, however, state when to prefer this over the neighboring restart_service or reconfigure tools, so the alternative-selection guidance is incomplete.

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

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

Annotations already flag a destructive, non-idempotent write, but the description adds real value beyond them: the lockout guard, the override escape hatch, and dry_run-as-preview. The [WRITE][risk=high] tag reinforces severity without contradicting the annotations.

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

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

Front-loads the risk/operation tag, then one explanatory paragraph, then a compact Args list. Every sentence is functional, though the prose paragraph could be tightened 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?

With no output schema and only hint-level annotations, the description supplies the mutation semantics, lockout risk, and dry-run preview an agent needs for a high-risk tool. It says nothing about post-commit state or response, a minor omission rather than a blocker.

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 there are no enums, so the description carries the full burden; it names all four parameters with meaning, including the filter/nat/aliases value set that the schema lacks. Only 'target' is thinly described, keeping it from 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 concrete verb (reload/commit) and resource (a subsystem's config), and enumerates the subsystems (filter/nat/aliases). It explicitly relates itself to the sibling apply_changes, so an agent can distinguish the two without opening a 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?

Explains that reloading the 'filter' subsystem commits staged rules just like apply_changes and shares its lockout guard and override, which is exactly the routing context an agent needs. It stops short of an explicit when-to-use-this-vs-apply_changes rule or a stated when-not condition, so it is clear but not fully prescriptive.

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 meaningfully beyond the annotations, which only say readOnly=false, destructive=true, idempotent=false. The description adds reversibility via undo, that prior entries are captured before the change, a risk=medium label, and a dry-run preview path. It does not state auth requirements or what happens when the entry is absent, so it stops short of a 5. Note the mild tension between 'reversible' and destructiveHint=true, though these are not contradictory (the removal destroys state until undone).

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][risk=medium] tag and the core action, then a compact Args block. Slightly redundant in stating dry-run preview twice (prose line and arg line), which keeps it from a 5.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers the essentials: scope of change, reversibility, prior-state capture, and a preview option. Missing edge-case behavior (entry not found, partial failure) and return shape, but nothing critical blocks correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden and does so for all four: name (source: list_aliases), entry (the host/network/port), dry_run (preview semantics), target (firewall target from config, omit for default). It doesn't specify entry formats or target naming conventions, leaving a small gap.

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

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

States a specific verb and resource: 'Remove one entry from an alias.' This cleanly distinguishes it from the sibling add_alias_entry and from alias_entries (which reads). An agent can select it without opening the schema.

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

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

Gives practical routing cues: the alias name comes 'from list_aliases', target comes 'from config', and dry_run previews the change. It doesn't explicitly state exclusions (e.g., when to prefer a broader alias rewrite over per-entry removal), but the context is clear enough to act on.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description goes well beyond them: it explains the concrete consequence of restarting the management service (connection killed, restart unobservable, undo cannot run) and declares a refuse-list. That is the kind of behavioral context 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-loads the [WRITE][risk=medium] tag then the purpose and the refusal rule, then the preview hint, then a compact args list. No wasted sentences, though the prose is slightly dense and could be trimmed marginally.

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 three-param destructive tool with no output schema, the definition covers safety, alternatives, and each parameter. It could say more about expected output or what 'reconfigure' family of siblings does vs. this, but the essential call information is 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 must carry parameter meaning. It does document all three params briefly (service, dry_run, target) and clarifies that target comes from config and can be omitted. However it adds no format details (e.g., accepted service-name spellings, target naming) and the service param lacks ambiguity resolution, leaving more to be desired given 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 write operation on a specific resource (restart a firewall service), and even names concrete service examples (unbound, dhcpd, openvpn). The scope is unambiguous and distinct from siblings like apply_changes or reboot.

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

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

Explicitly states when not to use the tool (the management-API services) and gives the alternative (console). Also points to dry_run=True as the preview path. This is exactly the when/when-not/alternative guidance a strong definition provides.

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 [READ] tag and readOnlyHint=true already establish the safe-read profile. The description adds useful context that the identifier is an OPNsense uuid or a pfSense id, but says nothing about return shape or behavior on an unknown id. Adequate rather than rich.

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 line followed by a compact args list with zero padding. Every line earns its place, though the args block is slightly list-like rather than prose.

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

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

For a read-only lookup with no output schema, the agent knows how to obtain the id and how target works, but gets no sense of what 'full detail' returns. Complete enough to invoke, not complete enough to anticipate the response.

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 load. It explains both parameters: uuid is an OPNsense uuid or pfSense id sourced from list_rules, and target is a firewall name from config that can be omitted for the default. Good 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 and resource: 'One rule's full detail by uuid/id.' It is clearly distinguishable from list siblings via the singular 'one rule', though it never names the sibling it complements (list_rules) or contrasts with rule_stats/rule_states.

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?

Implies the workflow by saying the uuid comes 'from list_rules', which hints at when to call this after listing. There is no explicit when-not or alternatives guidance, so usage is only implied rather than spelled out.

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, and the description adds real substance beyond that: the evaluation model ('compared in list order, top-down, exactly as pf evaluates them') and the fact that every finding names the offending/covering rule uuid. That operational detail is exactly what an agent needs to interpret results, though return-format caveats like the 'note' field are only gestured at.

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 [READ] marker and one-line summary, then uses labeled Args/Returns blocks. Every sentence is useful; the Returns block is justified because no output schema exists. Slightly verbose in the rules-field enumeration, 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?

With no output schema, the description documents the return dict keys (rulesEvaluated, unusedCount, shadowedCount, redundantCount, unusedRules, shadowedRules, redundantRules, note). Combined with full parameter coverage and the evaluation semantics, nothing material is missing for correct invocation or interpretation.

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: it documents all three parameters and even enumerates the expected fields of injected 'rules' rows (uuid, sequence, enabled, action, interface, protocol, source, destination, destinationPort, evaluations). It compensates well for the schema gap, with only minor ambiguity about the shape of 'target'.

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) and resource (enabled rules), then enumerates the three exact conditions detected: zero evaluations, shadowed by an earlier terminating rule, and redundant/identical duplicates. This distinguishes it clearly from siblings like rule_stats or list_rules, which count or enumerate rather than diagnose misconfiguration.

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 gives the two invocation modes: 'Pass rules for pure analysis, or a target to pull live.' That is clear context for selecting behavior. It stops short of naming alternative sibling tools or stating when-not to use it, so it is a strong 4 rather than 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?

readOnlyHint=true already establishes the safe-read profile, so the description's main added value is the 'top-N' limiting behavior and the note that omitting target falls back to a default. It does not disclose ordering, pagination, or what a returned state entry contains.

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

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

Purpose is front-loaded in the first sentence and the Args block is compact. The Args entries partially restate schema defaults, but nothing is bloated or buried.

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

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

For a read-only, two-parameter tool with no output schema, documenting both parameters and the defaulting behavior is largely sufficient. Only the ordering/selection logic of 'top' remains unstated.

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

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

Schema coverage is 0%, so the description must carry the params, and it does: it explains top is a count with a default of 50 and that target is a firewall target name from config that may be omitted for the default. This adds real meaning beyond the bare integer/string schema.

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

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

The description states a specific read action on a specific resource ('[READ] Active pf state-table entries associated with rules') and scopes it with 'top-N'. The phrase 'associated with rules' distinguishes it from the broader states_table sibling, though it never names that 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?

There is no guidance on when to choose this tool over states_table, rule_stats, or rule_detail, and no mention of exclusions or prerequisites. The '[READ]' tag hints at safety but not selection criteria.

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

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

readOnlyHint=true already declares the safety profile, so the description doesn't need to restate read-only behavior. It adds genuine value by disclosing sort order ('busiest first') and the top-N truncation, but says nothing about pagination, rate limits, or what the counts represent.

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 compact args block; nothing is padded. Minor redundancy in repeating 'busiest first' in both the header and the 'top' arg.

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 2-optional-param read-only tool with annotations covering safety and no output schema, the description covers purpose, ordering, and both parameters adequately. The remaining gap is the absence of any hint about output shape or how the counts are scoped.

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

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

Schema description coverage is 0%, so the description carries the full burden and mostly delivers: 'top' is explained as a count with default 20 and sort order, and 'target' as a config firewall name with an omit-for-default rule. This meaningfully exceeds the bare type/default info in the schema, though it doesn't state valid target values.

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

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

The opening line names a specific resource (per-rule hit counts / evaluations) and a distinguishing ordering trait (busiest first, top-N). An agent can tell what it returns, though the description never names a sibling such as rule_hit_and_shadow_analysis or rule_states to disambiguate which rule-stat view to pick.

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

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

There is no when-to-use or when-not-to-use guidance and no alternatives named, despite several overlapping siblings (rule_states, rule_hit_and_shadow_analysis, list_rules). The '[READ]' tag and 'omit for the default' note only cover mechanics, not selection.

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

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

Annotations already declare readOnlyHint=true and the '[READ]' tag reinforces it, so the safety profile is covered. The description goes further by disclosing the envelope shape, the truncation flag, and the default limit behavior, which is real behavioral context beyond the annotations.

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

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

One-line purpose followed by a compact Args block and a single envelope sentence. Nothing is redundant and the most important scoping information is front-loaded.

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

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

There is no output schema, yet the description describes the return envelope keys and the meaning of 'truncated', so the agent knows what it will get back. For a two-parameter read tool this is complete.

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

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

Schema description coverage is 0%, so the description carries the full burden for both parameters. It explains 'top' (count, default 100) and that 'target' is a firewall target name from config that can be omitted for the default, which fully compensates for the undocumented 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: reading active pf state-table entries, with the parenthetical clarifying these are tracked connections. It distinguishes the resource from siblings like rule_states and firewall_log, 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?

The '[READ]' tag and 'currently tracked' phrasing imply this is a live snapshot, which is useful context for when to reach for it. However, it gives no explicit when-to-use guidance relative to rule_states, kill_states, or top_talkers, and no exclusions or 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?

Goes well beyond the annotations: it discloses that the rule is read first so the harness records an undo restoring the prior enabled state, that changes are staged rather than immediate, and that dry_run offers a preview. This is exactly the mutation-side-effect context an agent needs.

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

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

Front-loaded with the operation class and risk, then behavioral notes, then a compact Args block. Every line earns its place, though the Args block is somewhat formatted-heavy for four short entries.

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

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

Covers prerequisites (uuid from list_rules), staging semantics, the required follow-up (apply_changes), preview mode, and default target behavior. With no output schema needed and annotations only covering safety flags, nothing an agent needs to call this 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%, so the description carries the full burden and does: uuid is defined as OPNsense uuid / pfSense id sourced from list_rules, enable is the target state, dry_run is a no-op preview, and target is a config-defined firewall name defaulting to the primary.

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 ('Enable/disable a filter rule') and immediately qualifies it with reversibility, making it distinguishable from siblings like add_alias_entry or kill_states. The [WRITE][risk=medium] tag front-loads the operation class.

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

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

Explicitly says the change is staged and that apply_changes is required to make it live, and that dry_run=True previews. It also points to list_rules as the source of the uuid, giving the agent both the prerequisite and the follow-up 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?

readOnlyHint=true already covers the safety profile, so the description earns credit for adding behavior beyond it: the exact response envelope and the meaning of 'truncated' versus 'total'. It stops short of noting units, sort order guarantees, or any rate/performance 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?

Front-loaded one-line purpose, then compact Args and Returns blocks. The envelope explanation is the only multi-line section and it directly prevents misreading the truncation flag, so every sentence earns its place.

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

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

There is no output schema, so the description supplies the return shape, and both parameters are documented despite 0% schema coverage. For a two-parameter read-only aggregation tool, nothing needed to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must carry the load and it does: 'top' is explained as the number of talkers returned (default 20) and 'target' as a firewall target name from config with explicit omit-for-default semantics, which the schema's bare string/null typing 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 specific resource ('busiest source hosts') plus the aggregation source and metric ('aggregated from the state table by bytes'), which cleanly separates it from siblings like states_table (raw rows) and firewall_log. An agent can identify the tool's output purpose 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?

The '[READ]' prefix and 'aggregated from the state table' hint at read-only traffic-volume analysis, and the target arg notes 'omit for the default'. But there is no explicit when-to-use/when-not guidance or routing to states_table, firewall_log, or blocked_traffic_rca for related questions; selection must be inferred.

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, idempotentHint=false and destructiveHint=true, so the safety profile is covered. The description adds genuinely new behavior: the inverse executes through its own governed, audited tool with its own risk tier, and a token can only be applied once. That single-use constraint is important and not derivable from the annotations.

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

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

Front-loads the write/risk tag and the core action, then layers behavioral notes. The Args block partially restates schema titles but adds real semantics; overall tight with minor 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?

With no output schema and a destructive write, the description covers the audit path, the preview path and the single-use limitation. It never says what a successful apply returns (though dry_run implies a preview payload), which is the main remaining 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 must carry the load, and it does: undo_id's provenance, dry_run's preview semantics, and target's pass-through behavior ('when it accepts a target'). The pass-through wording is slightly imprecise about when target is actually forwarded, keeping it out of 5 territory.

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

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

States a specific verb (apply) plus resource (a recorded undo) and clarifies the mechanism — dispatching the inverse tool. It is clearly distinguishable from the sibling undo_list, which is named as the source of the undo_id.

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

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

Tells the agent where the undo_id comes from (undo_list or an _undo_id in a write result) and when to use dry_run=True. It does not, however, state when not to apply an undo or compare against alternatives like apply_changes/reconfigure.

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.

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is to add beyond that. It does add value by enumerating the returned data (state, last handshake, transfer), which partially substitutes for the missing output schema, but it reveals nothing about permissions, target resolution behavior, or failure modes.

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 resource/payload in the first clause, with no filler. The Args block is a slightly mechanical way to present a single parameter but wastes nothing.

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 status tool with one optional param and no output schema, the description covers what is needed: what it returns, and how the target argument resolves. Nothing critical to correct invocation is missing, though error behavior and whether 'default' means default firewall target could be spelled out.

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 full burden for the single parameter, and it does: 'Firewall target name from config; omit for the default' explains both the value source and the default behavior. Slight gap in that valid target names are not described, but this is solid compensation for one param.

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 the specific resource (WireGuard peers) and what is reported (connected state, last handshake, transfer), which distinguishes it from siblings like openvpn_sessions and ipsec_sas. The verb is implied by the tool name/status pattern rather than stated outright, so it falls just short of a 5.

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

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

There is no when-to-use guidance and no alternatives named, even though sibling VPN/session tools (openvpn_sessions, ipsec_sas) exist. The only usage hint is that target may be omitted for the default, which is parameter guidance rather than tool-selection guidance.

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