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

With no annotations, the description carries the load and does so well: it discloses default method resolution, model validation of POST bodies, strict=false bypass, dry_run preview behavior, and the critical fact that changes are inert until apply/reconfigure runs. The notable gap is the 'confirm' flag, which for a tool that can restart services is likely a safety gate and is never explained.

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

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

Four dense sentences, each carrying a distinct behavioral fact, with the path grammar front-loaded followed by request-construction and activation caveats. No filler or restatement of the tool name.

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

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

For a 7-parameter untyped passthrough with no annotations and no output schema, the definition covers request construction and activation but omits the confirm gate, expected error/response shape, and routing guidance against 13 siblings. It is workable but leaves real ambiguity for a high-blast-radius tool.

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

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

Schema coverage is 0%, so the description must compensate and largely does: path format with examples, method defaulting, body validation, strict, and dry_run are all given meaning. The 'params' object and 'confirm' boolean remain undocumented in both schema and description, which keeps it short of full coverage.

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

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

The description names a concrete mechanism (raw endpoint call) and defines the path grammar as module/controller/action plus positional args, with two worked examples. It is clearly distinct from siblings like opn_api_describe and opn_items, though it never explicitly frames itself as the escape hatch after discovery tools fail.

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

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

It implies usage via examples and points at opn_items for the apply/reconfigure step, but gives no explicit when-to-use rule versus opn_api_search, opn_api_describe, or the dedicated wrappers (opn_service, opn_firewall_confirm). No exclusions or prerequisites are stated, leaving the agent to infer that this is the fallback for endpoints without a dedicated 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?

There are no annotations, so the description carries the full burden, but 'describe' strongly implies a read-only introspection call and the description does disclose what information is returned. It says nothing about permissions, failure modes when the path is unknown, or whether paths must come from opn_api_search, which is a real gap for an unannotated tool.

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

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

A single dense sentence plus an example, front-loaded with the returned data. The punctuation-as-list style ('Method, path args, body fields...') is slightly awkward 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 one-parameter tool with an output schema, the description covers what is returned and gives a path example. It still leaves the agent guessing how to obtain a valid path and what happens for an unrecognized endpoint, which matters because it is likely a prerequisite step in a multi-call workflow.

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. The example "firewall/alias/add_item" usefully establishes the path syntax, but 'path args' is ambiguous and the description never states whether the value is a bare endpoint identifier, needs a leading slash, or is a full URL.

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 resource precisely: it returns the method, path args, body fields (types, required, options) and search params of an endpoint, with a concrete example path. An agent can distinguish it from opn_api_search (find endpoints) and opn_api (invoke them), though the verb ('describe'/'look up') is only implied by the fragmentary phrasing.

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

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

No explicit when-to-use or when-not-to-use guidance is given. The natural workflow — call this to learn an endpoint's contract before invoking it via opn_api — is left entirely to inference, and no sibling is named as an alternative.

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

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

No annotations are supplied, so the description bears full disclosure burden; it identifies the matched fields but never states that the operation is read-only or how results are shaped/ranked. Critically, it omits that results are filtered to installed packages by default, which materially changes what the agent sees.

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

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

A single front-loaded sentence with the action first and illustrative queries last; nothing is wasted. Slightly dense with parenthetical examples but well structured.

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

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

An output schema exists, so return values need not be explained, but for a three-parameter search tool with zero schema documentation the description should still cover the installed-only default and limit behavior. As written, an agent cannot predict that uninstalled-package endpoints are excluded by default.

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

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

Schema description coverage is 0% across three parameters. The description compensates well for 'query' by explaining which fields are matched and giving example phrasings, but 'limit' and especially 'installed_only' (default true, which silently narrows results) receive no explanation anywhere.

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

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

The description uses a specific verb and resource ('Search OPNsense API endpoints') and clarifies the search surface: path, description, or model. The quoted example queries ('alias', 'kea reservation', 'unbound host override') make the intent concrete, though it never names the sibling opn_api_describe or opn_api to delimit itself.

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 phrasing and examples suggest this is a discovery step before calling opn_api or opn_api_describe, but there is no explicit when-to-use, when-not-to-use, or prerequisite guidance. An agent must infer the workflow from the sibling tool names.

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

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

With no annotations supplied, the description usefully discloses newest-first ordering, the listed fields, and the exact comparison performed in diff mode. However, it does not explicitly establish that the operation is read-only or describe the diff's output form and behavior when an ID is invalid.

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

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

The description is compact and front-loaded, covering the default result, ordering, fields, and alternate diff behavior in two efficient sentences. There is no unnecessary wording.

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

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

For a simple two-parameter tool, the description supplies most of what an agent needs to invoke both modes correctly, which is especially valuable without an output schema. The remaining gaps are the undocumented limit parameter, unspecified diff representation, and lack of an explicit read-only guarantee.

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

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

Schema description coverage is 0%, but the description compensates well for diff_with by identifying its value as a backup ID and explaining the comparison target. It adds nothing about limit beyond its name, such as confirming that it caps the number of returned history entries.

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

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

The description clearly identifies the resource as configuration history and explains its two capabilities: listing backups and producing a diff against the newest backup. It also specifies ordering and history fields, although it does not explicitly differentiate the tool from siblings such as opn_config_revert.

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 default history-listing context is clear, and "With diff_with=<id>" explicitly identifies when the diff mode is used. There is no guidance about when history or diff output is useful relative to other tools, such as inspecting a backup before reverting, nor any exclusions.

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

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

With no annotations, the description carries the full burden and does disclose a genuinely important trait: only the firewall picks up the new config immediately, while other services keep running on the old config until reconfigured. It also flags the confirm=true gate. It does not say whether the current config is preserved before overwrite or whether the action is reversible.

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

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

Three short sentences, front-loaded with the action and id source, then the caveat, then the confirm requirement. No filler, though the telegraphic phrasing leaves some edges rough.

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

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

The output schema exists, so return values need not be explained. However, for a destructive restore operation with zero annotation coverage and zero schema documentation, the silence on reload_firewall and on reversibility/current-config preservation leaves an agent without key decision information.

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

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

Schema description coverage is 0% across three parameters, so the description must compensate. It explains confirm=true and the provenance of 'backup', but reload_firewall (defaulting to true, with real consequences for the partial-apply behavior described) is never mentioned.

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: 'Restore config.xml from a history entry', and points to opn_config_history as the id source, which distinguishes it from the history-listing sibling. It does not, however, distinguish itself from opn_firewall_revert_now, the other revert-family tool in the sibling list.

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

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

Gives a clear when: restoring from a recorded history entry, and tells the agent where the required id comes from. It omits any when-not guidance or comparison to opn_firewall_revert_now / opn_firewall_confirm, leaving the agent to infer which revert tool to pick.

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

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

With no annotations, the description carries the full burden. It does disclose the safety-critical behavior — that confirming removes the rollback window by cancelling the auto-revert — but says nothing about required permissions, what happens if no pending revert exists, or whether the action is idempotent.

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

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

A single tight sentence with the commit action front-loaded and its side effect second. No redundant or filler wording.

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

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

An output schema exists and there are no parameters, so the description only needs to explain the commit semantics, which it does. The minor gap is the absence of any failure-mode or prerequisite note for a rollback-cancelling operation.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter confusion is possible.

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 specific verbs and object: it keeps the applied firewall changes and cancels the pending auto-revert. The effect is unambiguous and distinct from opn_firewall_revert_now, though the sibling is never named explicitly.

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

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

Usage is implied: call after applying firewall changes when you want them to persist. There is no explicit statement of when not to use it, no reference to opn_firewall_revert_now as the alternative path, and no mention of whether an auto-revert must actually be pending.

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

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

No annotations are supplied, so the description carries the full burden. It does add useful behavior – results are ordered newest first and the filter scans IP, port, and interface – but it never says what 'recent' means (time window or buffer size), whether the limit truncates the newest or oldest end, whether search is case-sensitive or regex, or if any privileges are needed. For a zero-annotation tool this leaves substantial behavioral gaps.

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

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

A single parenthetical sentence that front-loads the resource and ordering before the optional filter. Every clause carries information; there is no filler or repetition.

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

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

An output schema exists, so return-value documentation is not required, and the filter and ordering are covered. However, with no annotations and 0% schema coverage, the missing definition of 'recent', the role of limit, and the read-only/permission profile leave the definition only minimally adequate for an agent to call it confidently.

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

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

Schema description coverage is 0% and the schema only supplies titles and defaults, so the description must compensate. It fully explains the 'search' parameter (substring matched against IP, port, or interface), which is genuinely useful, but says nothing about 'limit' – neither its effect nor how the default of 100 behaves.

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

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

Names a specific resource (firewall log entries), the ordering (newest first), and the optional substring filter over IP/port/interface, so an agent knows exactly what comes back. It stops short of distinguishing itself from siblings like opn_config_history or opn_overview, which also expose operational data.

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?

Use is implied rather than stated: 'optionally filtered by a substring' hints at when the search parameter applies, but there is no explicit when-to-use, when-not, or pointing to a sibling for other data. An agent must infer that this is the log-inspection tool rather than, say, a config or settings reader.

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

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

No annotations are supplied, so the description carries the full burden. It usefully discloses the existence of a pending-change timer, but it never states whether the unapplied changes are discarded, whether the revert is irreversible, or whether any privilege is required. An output schema exists, so return-value detail is not expected here.

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

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

A single economical sentence that front-loads the action and then adds the one qualifier that matters. Nothing is redundant and nothing could be trimmed without losing meaning.

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

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

For a zero-parameter action with an output schema, this is close to sufficient: the agent knows what it does and when it fires. The only real gap is that it does not situate the tool within the confirm/pending-revert workflow alongside its siblings.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies no inputs are needed.

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

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

The description uses a specific verb+resource pair ("revert the pending firewall changes") plus a timing qualifier ("immediately instead of waiting for the timer"), so the action is unambiguous. It does not, however, distinguish itself from siblings like opn_config_revert or opn_firewall_confirm, which an agent may well confuse with this one.

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

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

The phrase "instead of waiting for the timer" implies the situation in which to call it: a deferred revert is pending and you want it to happen now. There is no explicit when-not guidance and no sibling named as an alternative (e.g. confirm vs revert), leaving the agent to infer the choice.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: apply triggers reconfigure, firewall-rule applies arm an auto-revert that needs opn_firewall_confirm, and deletes require confirm=true. However it omits that action defaults to "search" (so the tool reads by default) and that apply defaults to true, meaning mutations reconfigure by default — a significant undisclosed side effect. No return shape or error behavior is described.

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 controller+item model, followed by compact parenthetical examples and short clauses on apply, auto-revert, and confirm. The endpoint example list is long but each entry is load-bearing for discovery. No filler sentences.

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

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

This is an 11-parameter, multi-operation mutation tool with no annotations and no output schema, so the description should be thorough. It covers lifecycle side effects well but leaves the operation selector, dry_run, uuid targeting, pagination, and filtering entirely unexplained, so an agent cannot reliably invoke non-default actions from this definition alone.

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

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

Schema description coverage is 0% across 11 parameters, so the description must compensate and only partly does: controller, item (with the endpoint mapping examples), data, apply, and confirm are explained. Six parameters remain undocumented anywhere, including action with its six-value enum (search/get/add/set/del/toggle), plus uuid, search, rows, enabled, and dry_run — the most consequential gap being the parameter that selects read versus write.

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?

"Work with the items of any OPNsense model controller" is a somewhat generic verb, but the controller+item mapping formula and the six concrete endpoint examples (firewall/alias, unbound/settings host_override, kea/dhcpv4 reservation, etc.) make the scope concrete. An agent can tell this is the generic per-item CRUD tool rather than a search or describe tool, though it never names a 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?

Gives clear conditional guidance: apply=true triggers the controller's apply/reconfigure, firewall rules arm auto-revert which must be confirmed with opn_firewall_confirm, and del requires confirm=true. It also routes to opn_api_describe for field names. It lacks any when-not guidance or explicit comparison to opn_api/opn_settings/opn_api_search, so it falls 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?

No annotations are supplied, so the description carries the full burden; it does establish that this is a passive table read with no mutation implied. It does not mention permissions/authentication requirements, whether an empty table is an error or an empty list, or result size limits. With an output schema present, the return shape is covered elsewhere, which keeps this from being a larger gap.

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

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

A single front-loaded sentence with no filler; the resource comes first and the optional modifier second. Nothing is redundant with the schema.

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

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

For a two-parameter, default-all read tool with an output schema, the description covers the resource and both parameters' semantics. Only minor gaps remain: default behavior when no filter is given and any permission assumption.

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 parameters are bare enums/unnamed, yet the description supplies the key semantics: 'family' selects the protocol (ipv4→ARP, ipv6→NDP) and 'search' matches IP, MAC, or hostname substring. That is exactly the meaning the schema lacks, so the description meaningfully compensates for the coverage gap.

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

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

The sentence names the concrete resource (ARP table for ipv4, NDP table for ipv6) and its optional filtering, so an agent knows exactly what data comes back. It is a clear verb-less but unambiguous 'read this table' definition; it just doesn't differentiate against siblings, though the sibling list (api_search, ping, firewall_*) contains nothing overlapping.

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

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

The phrase 'optionally filtered by IP/MAC/hostname substring' implicitly tells the agent to use the search parameter for lookups by address, MAC, or name, which is the main usage decision here. There is no explicit when-to-use/when-not guidance or mention of alternatives (e.g. when to use a general item lookup instead).

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

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

No annotations are supplied, so the description carries the full behavioral burden. It helpfully discloses that the response includes 'whether writes are enabled' (a config-state flag likely relevant before any mutation), but it never explicitly states that this call itself is read-only and side-effect free, nor does it mention permissions or cost.

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

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

A single sentence, front-loaded with the returned contents and ending with the one non-obvious flag (writes enabled). No filler, no restatement of the tool name.

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 no-argument status tool with an output schema that already documents the return shape, the description covers the essential scope. The only missing piece is an explicit statement that the call is read-only, which matters given the absence of annotations.

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

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

The tool takes zero parameters, and the description correctly adds no parameter guidance. Baseline of 4 applies since there is nothing further the description could clarify about inputs.

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

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

The description enumerates exactly what the tool returns (version, update status, interfaces, gateways, services) and the 'in one call' phrasing signals an aggregated snapshot, distinct from the narrower siblings like opn_service and opn_items. It lacks an explicit verb (e.g., 'returns'/'summarizes') and never names a sibling it supersedes, so differentiation is inferred rather than stated.

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

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

The 'in one call' framing implies this is the cheap orientation call to make before drilling into opn_items, opn_service or opn_settings, but no when-to-use or when-not-to-use condition is stated. An agent must infer that this is a broad snapshot tool rather than a targeted query.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the key behavioral facts: the operation is effectively read-only and it creates a temporary diagnostics job that is removed afterwards, so an agent knows nothing persists. It doesn't cover permissions, blocking duration, 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?

Two tightly written sentences with no filler. The core action is front-loaded and the read-only caveat follows immediately.

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

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

An output schema exists, so the description needn't explain return values, and the tool's complexity is low. However, with zero schema coverage on three parameters, the definition is not complete enough for an agent to confidently supply 'count' and 'timeout' without guessing units.

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

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

Schema description coverage is 0% and the description mentions none of the three parameters. The meaning of 'count' (number of echo requests, default 3) and 'timeout' (implicitly seconds, default 30) is left entirely to the agent's inference, so the description does not compensate for the coverage gap.

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

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

The description states a specific verb and resource: 'Ping a host from the firewall', and it also names the outputs (loss and round-trip times). It is immediately distinguishable from every sibling, none of which performs diagnostics, though it doesn't explicitly say so.

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 use case (connectivity diagnostics from the firewall) is implied but never stated as a condition, and no alternatives or exclusions are given. There is no guidance on when a different tool (e.g., log or neighbor lookup) would be preferable.

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

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

With no annotations at all, the description carries the full burden. It does disclose one critical behavioral constraint – stop needs confirm=true – which is genuinely useful for a mutating action. But it does not say whether start/stop/restart require elevated permissions, whether restart interrupts traffic or drops connections, or what happens if the service name is unknown, leaving meaningful gaps for a state-changing tool.

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

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

Two compact sentences with no filler, and the mode-selection rule is front-loaded before the confirmation requirement. The nested parenthetical of example service names makes it slightly harder to scan, 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?

For a four-parameter tool with no output schema and no annotations, the description covers the routing decision, parameter purposes, and the one safety precondition needed to call it correctly. Missing are return-value expectations and permission or failure behavior, which are minor for a simple service-control endpoint.

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

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

Schema description coverage is 0%, so the description must compensate and largely does: name is the service to act on (with examples), service_id is for multi-instance services, and confirm gates stop. Only 'action' remains under-explained, since the status value is not described even though the listing behavior is implied.

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

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

The description states a specific resource (services) and both modes of operation: listing when no name is given, and start/stop/restart when a name is supplied. It gives concrete service names ("unbound", "dhcpd", "openvpn") and distinguishes single- versus multi-instance services. It stops short of a 5 because the schema's 'status' action is never named explicitly, so an agent must infer that 'list services (no name)' maps to that enum value.

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

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

It clearly conditions behavior on the name parameter and adds the hard prerequisite that stop requires confirm=true, plus the multi-instance hint for service_id. That is actionable when-to-use guidance. It does not, however, point to sibling tools for related operations (e.g. opn_items or opn_overview) or state when not to use it.

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

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

With no annotations, the description carries the full burden and does disclose the key non-obvious behavior: data is merged into the model rather than replacing it, and apply triggers a service reconfigure. It omits whether the operation is reversible, what permissions are required, and what dry_run actually changes about the call, leaving the mutation's risk profile partially undisclosed.

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

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

Compact and front-loaded, leading with the read case before the write case, with a single inline example that earns its place. The 'or change part of it:' clause is slightly awkward but not wasteful.

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

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

For a mutation tool with no annotations, no output schema, and zero schema description coverage, the description covers the essential read/merge/apply flow but leaves dry_run unexplained and gives no sense of the return value or error behavior. Adequate, but there are clear gaps an agent would want filled.

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

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

Schema description coverage is 0%, so the description must compensate. It explains data's merge semantics and gives a concrete example, and explains apply's effect, but says nothing about dry_run or the required controller parameter, leaving two of four parameters with no semantics anywhere.

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

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

States a specific verb pair (read vs. change) against a concrete resource ('a controller's whole settings model') and names the underlying endpoints controller/get and controller/set. It does not differentiate itself from siblings such as opn_api or opn_service, which plausibly also touch configuration, 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?

The description implicitly defines two modes: omit data to read, supply data to merge-and-save, and apply=true to run the reconfigure. That is useful implied routing, but there is no explicit when-not guidance, no mention of dry_run as a safer alternative, and no pointer to sibling tools for arbitrary endpoints.

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