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

No annotations are provided, so description carries full burden. It states aliases are 'metadata definitions that only affect traffic when referenced by a firewall rule' and that no savepoint protection is needed. This discloses non-destructive behavior. However, it does not mention authentication or other potential side effects.

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

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

The description is well-structured with a clear lead sentence, usage guidance, and a parameter list. It is not overly verbose, though the parameter explanation could be slightly more concise. Still, every sentence serves a purpose.

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

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

The description is complete for the tool's complexity. It explains the tool's purpose, parameter details, return format (dict with result and uuid), and behavioral notes (no savepoint). With output schema present and no annotations needed, the description fully enables correct agent 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%, but the description explains all four parameters in detail. It provides constraints (e.g., name: alphanumeric and underscores only), examples for content (GeoIP country codes like 'DE\nFR\nNL'), and enumerates alias_type options. This adds significant value beyond the basic 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 clearly states 'Create a new firewall alias' with specific verb and resource. It lists the types of aliases (IP list, network group, port group, etc.), distinguishing it from sibling tools like list, delete, update, and toggle.

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

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

Provides explicit guidance: 'Use this when you need to create a reusable alias for use in firewall rules.' Also notes that savepoint protection is not required. While it doesn't explicitly exclude other use cases, the context makes it clear when to use this tool versus alternatives.

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

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

No annotations are provided, so the description must disclose all behavioral traits. It implies a write operation but does not mention authentication requirements, side effects (e.g., immediate application, need for commit), or potential failure modes. This is a significant 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?

The description is two sentences, the first stating the action and the second providing context. It is concise, front-loaded, and contains 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?

Given the presence of an output schema and high schema coverage, the description is mostly complete for parameter understanding. However, it lacks behavioral transparency and usage exclusions, leaving some gaps for an agent.

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

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

Schema description coverage is 100% with detailed parameter descriptions (e.g., checkip explains IPv6). The description adds no extra semantics beyond the schema, meeting baseline of 3.

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

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

The description clearly states the tool creates a new Dynamic DNS account and applies configuration. It distinguishes from sibling tools like opn_list_ddns_accounts, opn_update_ddns_account, opn_delete_ddns_account by focusing on creation.

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 explains when to use the tool (to register a hostname with a DDNS provider for automatic IP updates). It does not explicitly state when not to use it or compare alternatives, but the context is clear enough for most agents.

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 full burden. It explains key behaviors: 'without overwriting existing entries,' 'Changes are applied immediately,' and lists the return structure (dict with added, already_present, etc.). While it doesn't detail permissions or persistency, it provides sufficient behavioral context for an additive write operation.

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

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

The description is concise and well-structured. It starts with the core purpose, then usage context, prerequisite, parameter list, and return fields. Every sentence adds value with no redundancies. Information is front-loaded and easy to scan.

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

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

Given the tool's simplicity (2 required params, simple return dict) and presence of output schema (explained in description), the description covers all essential aspects: purpose, when to use, prerequisite, parameter details, and return format. No gaps remain for an AI agent to infer.

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. It clearly defines each parameter: uuid as 'blocklist UUID from opn_list_dnsbl' and domains as 'domains to add, comma or newline-separated'. This adds significant meaning beyond the bare schema types and includes format guidance for the domains string.

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

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

The description clearly states 'Add domains to a DNSBL allowlist (whitelist) without overwriting existing entries,' specifying the action (add), resource (DNSBL allowlist), and key behavior (non-destructive). It distinguishes from sibling tools like opn_remove_dnsbl_allowlist and opn_set_dnsbl by emphasizing additive nature and preservation of existing entries.

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 'Use this when a domain is blocked by DNSBL and you need to allowlist it,' providing a clear use case with an example. It also instructs to 'Get the UUID from opn_list_dnsbl first,' indicating a prerequisite. However, it does not explicitly mention when not to use or point to alternative tools (e.g., opn_remove_dnsbl_allowlist for removal), which would improve differentiation.

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 provided, the description must cover behavioral traits. It mentions 'apply the configuration' indicating a side effect, but does not disclose permissions needed, potential conflicts, reversibility, or what happens on failure. This is insufficient for a configuration mutation tool.

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

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

The description is two sentences: first states the core action and effect, second provides usage context. Every sentence is necessary and front-loaded. No wasted words.

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

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

Given the tool's complexity (7 parameters, optional RA), the description adequately covers purpose and IPv4/v6 distinction. It does not explain return values (output schema exists) or error conditions, but it is sufficient for a create operation with good schema documentation. Slightly incomplete for a high-complexity 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 100%, so parameters are well-documented in the schema. The description adds minimal extra value beyond the schema, like clarifying 'apply the configuration'. It does not explain parameter dependencies or provide extensive additional context. Baseline 3 is appropriate.

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

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

The description clearly states the action (create) and resource (dnsmasq DHCP range) with the specific verbs 'Create' and 'apply'. It distinguishes from sibling tools like opn_delete_dnsmasq_range and opn_update_dnsmasq_range by specifying 'add' and describing DHCP range creation.

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

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

The description explicitly says 'Use this to add DHCPv4 or DHCPv6 address ranges with optional Router Advertisement (RA) configuration', providing clear context for usage. However, it does not explicitly state when not to use this tool or mention alternatives among siblings, though the sibling names imply distinct roles.

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 fully covers behavioral traits: changes are applied immediately (Unbound reconfigured automatically), and DNS overrides cannot be auto-reverted. This allows the agent to understand the consequence of calling the tool.

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

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

The description is well-structured with a summary, usage context, behavioral notes, parameter list, and return format. It is slightly verbose but every sentence adds necessary information; could be tightened without losing clarity.

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

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

Given no annotations, zero schema coverage, and presence of output schema, the description is remarkably complete. It covers purpose, usage guidelines, behavior, parameter semantics, and return format, leaving no important gaps for agent decision-making.

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%, but the description explains each parameter's meaning: hostname as 'e.g. 'myserver'', domain as 'e.g. 'local.lan'', server as 'IP address to resolve to (IPv4 or IPv6)', and description as optional. This adds significant value 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?

The description clearly states the purpose: 'Add an Unbound DNS host override (A/AAAA record) and apply immediately.' It distinguishes from sibling tools like opn_list_dns_overrides (to check existing) and opn_delete_dns_override, making the action and resource specific.

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

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

Explicitly tells when to use: 'when you need to create a local DNS record... for split-horizon DNS, internal services, or overriding external DNS.' It also advises caution: 'cannot be auto-reverted — verify settings before calling' and recommends checking existing overrides with opn_list_dns_overrides first.

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

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

With no annotations, the description notes that 'creating one does not affect traffic or rules,' providing safety context. It also states the return type, but lacks details on error conditions or idempotency.

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?

Concise with clear sections: purpose, usage guide, parameter list, return info. Every sentence adds value with no redundancy.

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

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

For a simple parameter set (2 params, no nested objects) and presence of output schema, the description fully covers what the tool does, its parameters, and what it returns.

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?

Adds constraints not in schema: name length (1-255 chars), no commas, and color format (hex without '#') with example and default. Schema coverage is 0%, so this is valuable.

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?

Clearly states 'Create a new firewall rule category' as a specific verb+resource. Distinguishes from siblings like opn_add_firewall_rule by emphasizing categories are metadata and do not affect traffic.

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 'Use this when you need to create a category for organizing firewall rules.' While it doesn't mention when not to use, the context makes it clear for category creation vs. rule creation.

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 exist, so the description must carry behavioral info. It explains savepoint auto-revert behavior (60 seconds, version-dependent), the need to confirm changes via opn_confirm_changes, and the distinction from legacy rules. This is exactly what 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?

Well-structured with a summary then parameter list Baby steps, but it's long. However every sentence adds value (savepoint, version behavior, param details). Could be slightly trimmed but not bloated.

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 17 params and version-dependent behavior, the description covers savepoint semantics, version differences, backup guidance, and every parameter's meaning. No gaps.

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

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

Schema has 0% coverage; the description's parameter list gives meaning to all 17 params including defaults and inversion semantics (source_not: invert match). Each param has a brief but clear explanation.

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

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

The description clearly states the tool 'Create[s] a new MVC firewall filter rule' with a specific verb and resource. It also distinguishes from other firewall tools by noting it's for MVC rules, not legacy GUI rules, and references related tools 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?

The description says 'Use this when you need to add a firewall rule' and warns to check opn_mcp_info for savepoint support. However it doesn't explicitly state when NOT to use it (e.g., for legacy rules), though the MVC emphasis essentially implies that. No explicit alternatives mentioned beyond savepoint.

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 fully carries the behavioral disclosure. It details the created rules, savepoint behavior on OPNsense <26.7 (auto-revert in 60s unless confirmed), and immediate application on 26.7+. It also warns about potential lockout and suggests mitigation, covering important side effects without contradicting any annotations.

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

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

The description is well-structured and front-loaded with purpose and usage. It lists the 5 rules concisely, then notes version-specific behavior, parameters, and return type. Every sentence adds value; no fluff, and it's easy to scan.

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

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

For a tool that creates multiple rules with version-dependent behavior, the description is remarkably complete. It explains the rules created, version differences, confirmation process, and required pre-checks (savepoint_support and backups). The return format (revision, rules, instructions) is also specified, making the tool fully understandable without additional context.

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. It clarifies the sole parameter 'interface' with examples ('lan', 'opt1', 'opt2') and indicates default 'lan'. While minimal, it adds enough meaning for a simple parameter, though it could explicitly state it's the OPNsense interface name.

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

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

The description clearly states the tool creates essential ICMPv6 firewall rules for IPv6 operation. It specifies the exact resource (ICMPv6 rules) and distinguishes from generic firewall rule tools by focusing on the mandatory ICMPv6 set (5 specific rules per RFC 4890).

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 'Use this when setting up IPv6 on an interface' and explains why ICMPv6 is mandatory, providing strong context. It also gives operational guidance for different OPNsense versions, recommending checks via opn_mcp_info and backups via opn_download_config. This well differentiates from alternatives like opn_add_firewall_rule.

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

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

It discloses the savepoint protection mechanism, including the version-specific behavior (auto-revert on <26.7, immediate on 26.7+), and warns about the risk of lockout if not handled properly.

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 relatively concise but contains redundant warnings about the savepoint behavior, repeating information in multiple sentences. It could be streamlined, but remains clear and 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?

The description gives enough context for the tool's purpose and key behaviors, but it does not mention the return value (though output schema exists) or any prerequisites. It does cover the main warning about savepoint and lockout. Overall, it is adequate but could be enhanced with parameter explanations.

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 description does not explain the meaning of any of the parameters (protocol, interface, target_ip, description, target_port, destination_port). It only refers to 'external port' and 'internal host' without linking to specific parameter names, leaving the parameter semantics unclear.

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

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

The description clearly states that the tool creates a NAT port forwarding rule and explains the use case: forwarding an external port to an internal host. This distinguishes it from general firewall rules and aligns with its name.

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

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

It explicitly says 'Use this when you need to forward an external port to an internal host' and provides important caveats about savepoint behavior and steps to check opn_mcp_info and take backup if needed.

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

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

No annotations exist, so the description carries the full burden, and it does most of the job: 'Get' implies a non-mutating read, and the return body is spelled out (rows with ip, mac, intf, hostname, plus rowCount). It omits whether entries come from the live cache versus static config, or how multiple interfaces are reported, which matters for interpreting 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?

Three short, front-loaded sentences: purpose, usage, return shape. The returns sentence partially duplicates the output schema that already exists, but it is compact and does not bloat the definition. No 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?

For a zero-parameter read tool with an output schema present, the description covers purpose, when to call, and what comes back — nothing essential is missing. The only real gap is the absent pointer to opn_ndp_table for IPv6 neighbors, which would help in an environment with many similar monitoring 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?

The tool takes zero parameters, so per the baseline this scores 4; there is no parameter meaning the description needs to add. It does explicitly say the query is unfiltered (whole ARP table returned), which usefully implies no scoping arguments.

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 concrete verb+resource pair, 'Get the ARP table showing IP-to-MAC address mappings', which tells the agent exactly what data comes back. It does not explicitly distinguish itself from the sibling opn_ndp_table (IPv6 neighbor table), leaving that IPv4-vs-IPv6 split to inference from the name.

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 this when you need to find which MAC address is associated with an IP, identify devices on a network segment, or troubleshoot connectivity' gives three concrete triggering scenarios. It stops short of exclusions or naming an alternative tool (e.g. opn_ndp_table for IPv6, opn_list_dhcp_leases for lease lookups), so routing to the right sibling is only partly supported.

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 must fully disclose behavior. It mentions relaying mDNS packets (224.0.0.251:5353) between selected interfaces and enabling specific protocols, but does not cover potential side effects (e.g., whether it overwrites existing config, requires restart, or is reversible). This is adequate but not comprehensive.

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

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

The description is two sentences long, efficiently front-loading the purpose in the first sentence. The second sentence adds valuable context (cross-VLAN, specific devices). No wasted words. Concise and well-structured.

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

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

Given the tool has only two simple parameters, the description provides sufficient context for use. It explains the use case (cross-VLAN mDNS) and typical supported devices. The presence of an output schema (not shown) likely covers return values. Completeness is good for a configuration 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?

Input schema coverage is 100% and both parameters ('enabled' and 'interfaces') are clearly described. The description does not add new meaning beyond the schema; it restates that the repeater relays between interfaces. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Enable and configure the mDNS Repeater to relay multicast DNS between interfaces.' It uses specific verbs ('configure') and resources ('mDNS Repeater'), distinguishing it from sibling tools like 'opn_mdns_repeater_status' which only retrieves status.

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

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

The description explicitly advises when to use this tool: 'Use this to set up cross-VLAN mDNS discovery.' This is clear context, though it does not mention when not to use it or provide alternative tools for related tasks. However, given the sibling set includes a status-only tool, the recommendation is sufficient.

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

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

With no annotations, the description carries full burden. It transparently discloses the effect (cancels auto-rollback), the timing constraint, and the no-op behavior on newer versions. It also mentions the return type, which is helpful.

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

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

The description is concise (about 4 sentences) and front-loaded with the main purpose. It uses clear sections for timing and version notes without any unnecessary verbosity.

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 confirmation tool, the description covers the purpose, when to use, the 60-second window, version dependency, and return type. It is complete enough for an agent to invoke correctly without additional context.

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

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

The schema has a single required parameter 'revision' with no description (0% coverage). The tool description implies that revision comes from a prior write operation, mentioning that write tools return an empty revision on newer versions. This provides some context but does not explicitly define the parameter's format or how to obtain it, leaving a 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 clearly states the tool confirms pending firewall changes, distinguishing it from sibling write tools. It uses a specific verb (confirm) and resource (firewall changes), and the phrase 'cancelling the 60-second auto-rollback' adds specificity.

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

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

It explicitly instructs to use AFTER applying firewall changes and mentions the 60-second window. It also states that it's only relevant on OPNsense < 26.7, providing clear exclusions and alternatives (no-op on newer versions).

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 provided, but the description implies a read-only operation ('List') and specifies the return format. No contradictions or destructive hints.

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

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

The description is very concise, with two sentences plus a note, front-loading the purpose and structure efficiently.

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

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

Output format is described, and the prerequisite is stated, but parameter explanations are missing, making the tool somewhat incomplete for correct invocation.

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

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

Schema description coverage is 0%, and the description does not explain the purpose or behavior of parameters 'search' and 'limit', offering no additional meaning beyond defaults.

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

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

The description clearly states the tool lists CrowdSec security alerts (detected threats and attacks), specifying types like brute-force and port scans. It distinguishes from sibling tool opn_crowdsec_status.

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 provides clear context (review security events) and notes a prerequisite (CrowdSec plugin). It lacks explicit alternatives or when-not-to-use 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?

No annotations, but description clearly states it's a read operation returning specific keys. Discloses plugin dependency. Does not detail any side effects (likely none), which is fine.

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 succinct sentences: purpose, usage guidance, return info. No wasted words, 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?

Given no parameters and presence of output schema, description covers all needed: purpose, when to use, prerequisite, return keys. Complete for its complexity.

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

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

No parameters. Schema coverage is 100%, so description need not add param info. Baseline 4 for zero-param tools.

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?

Clearly states it retrieves CrowdSec status and decisions summary. Distinguished from sibling opn_crowdsec_alerts by focusing on status and total counts, not individual alerts.

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 when to use: to check if CrowdSec is running, see active decisions count, and get threat overview. Mentions plugin requirement. Could mention when not to use, but overall helpful.

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?

Discloses that deletion is immediate, does not use savepoint protection, and that referenced aliases cause rules to stop matching traffic. With no annotations, this provides essential 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?

Concise, front-loaded with the action, then important warnings and usage hints. Every sentence adds value, no redundancy.

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

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

Covers the single parameter, preconditions (finding UUID, checking rules), side effects (immediate, no savepoint), and return format. With output schema present and description covering return keys, it is fully adequate for use.

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?

Though schema has 0% coverage, the description tells that the uuid is from opn_list_firewall_aliases and the action is deletion by UUID. Adds meaning beyond the bare schema by explaining the source and purpose of the 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?

Clearly states 'Delete a firewall alias by UUID', which is a specific verb+resource. It distinguishes from siblings like opn_list_firewall_aliases, opn_add_alias, and opn_update_alias by focusing on deletion.

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

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

Explicitly instructs to use opn_list_firewall_aliases first to find the UUID, and warns to check for referencing firewall rules using opn_list_firewall_rules. Provides clear when-to-use guidance with step-by-step 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?

No annotations are provided, so the description carries the full burden. It discloses that the deletion is applied immediately and triggers automatic reconfiguration of ddclient. It also specifies the return format. However, it could mention that the action is irreversible or note permission requirements.

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

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

The description is three concise sentences, each providing essential information: the action, immediate effect, prerequisite, and return format. No redundant or verbose phrasing. Very 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?

The description covers the core action, prerequisite steps, behavioral side effects, and return value structure. For a simple one-parameter deletion tool, this is fully complete and aids 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 coverage is 0%, but the description explains the parameter's purpose ('by UUID') and directs the user to list DDNS accounts to find it. This adds meaningful context beyond the schema's type-only definition.

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

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

The description clearly states the action 'Delete a Dynamic DNS account by UUID'. It distinguishes the tool from siblings like opn_add_ddns_account and opn_update_ddns_account by specifying deletion. The verb and resource are specific and unambiguous.

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

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

The description advises using opn_list_ddns_accounts first to obtain the UUID, which is a clear prerequisite. It mentions that deletion is applied immediately with automatic reconfiguration. However, it does not explicitly state when to avoid using the tool (e.g., irreversible action), but the context is sufficient for correct 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?

Discloses immediate application and automatic reconfiguration. With no annotations, description carries full burden; however, it lacks details on irreversibility, permissions, or error handling.

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

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

Three concise sentences, each serving a purpose: action, immediacy, prerequisite and return type. No redundancy.

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

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

Covers key aspects: what it does, how to prepare (list prerequisite), immediate effect, and return value. For a simple one-param delete, it is sufficient; missing error behavior.

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 has 0% description coverage; description compensates by explaining UUID parameter's role (identifier for the range). Could include format hint like 'UUID string'.

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?

Clearly states verb 'Delete', resource 'dnsmasq DHCP range', and method 'by UUID'. Distinguishes from siblings like opn_add_dnsmasq_range and opn_update_dnsmasq_range.

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

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

Provides explicit prerequisite: 'Use opn_list_dnsmasq_ranges first to find the UUID.' Mentions immediate application. Does not mention when-not-to-use or alternative tools, but context is clear.

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

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

With no annotations provided, the description fully carries the behavioral burden. It states the deletion is applied immediately, Unbound is reconfigured automatically, and changes cannot be auto-reverted. It also describes the return value structure, which adds transparency beyond the bare 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?

The description is concise with three sentences, each serving a purpose: action, effect, warning/prerequisite, and return. No superfluous words, but could be slightly more structured.

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

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

For a simple delete tool with one parameter, the description covers the essential aspects: what it does, the immediate effect, prerequisites, and return format. It is nearly complete but lacks details on error handling or UUID format.

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 mentions 'by UUID' but provides no format, example, or explanation of what constitutes a valid UUID for the uuid parameter. The description adds minimal value over the schema.

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

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

The description clearly states the action 'Delete an Unbound DNS host override by UUID' and specifies the resource (DNS host override) and method (by UUID). It is distinct from sibling tools like opn_add_dns_override and opn_update_dns_override.

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 provides a prerequisite: 'Use opn_list_dns_overrides first to find the UUID.' It also warns about irreversibility and to verify UUID before calling. It does not explicitly mention when to avoid the tool, but the context is clear enough.

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

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

With no annotations, the description fully discloses behavior: savepoint protection on OPNsense < 26.7 with auto-revert, immediate changes on 26.7+, and the return dict structure. It also warns about potential lockout and advises checking opn_mcp_info for support and taking a config backup if needed.

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 several sentences long but each adds value, covering purpose, prerequisites, version nuances, backup advice, and return info. It is front-loaded with the core purpose and structured into logical paragraphs, though it could be slightly more succinct without losing essential details.

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

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

For a destructive, version-sensitive operation, the description covers all critical aspects: pre-deletion steps, version-specific behavior, backup strategy, and return format. It addresses the complexity of the tool and compensates for the lack of annotations and parameter descriptions thoroughly.

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 only parameter 'uuid' is described as 'by UUID' and the description points to the list tool for finding categories, adding guidance beyond the schema. However, it does not detail the expected format or constraints of the UUID, leaving some ambiguity for a single undocumented parameter.

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

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

The description clearly states the tool 'Delete a firewall rule category by UUID' with a specific verb and resource, distinguishing it from sibling tools like add, list, and set categories. It also mentions savepoint protection, adding scope and context.

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

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

Explicit guidance is provided: 'IMPORTANT: Reassign rules to other categories BEFORE deleting... Use opn_list_firewall_categories to find categories and opn_set_rule_categories to reassign rules first.' It also specifies that system defaults cannot be deleted and gives version-specific instructions, including a backup recommendation when savepoint support is absent.

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

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

No annotations are provided, so the description carries the full burden. It discloses savepoint behavior including version differences (OPNsense < 26.7 vs 26.7+), auto-revert timing, and the need for confirmation or backup. It also notes that changes apply immediately on 26.7+, which is critical behavioral context. However, it doesn't detail potential side effects like lockout risk beyond the hint.

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

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

The description is well-structured and front-loaded. The first sentence states the action, and subsequent paragraphs cover usage, savepoint protection, and return values without redundancy. It is concise yet detailed, with every sentence providing necessary context.

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

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

Given the tool's complexity (savepoint handling, version differences, backup recommendation) and the absence of annotations, the description is thorough. It explains the return values ('revision' and 'result'), and references prerequisite tools. With a single parameter and output schema, 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 coverage is 0%, so the description must compensate. It explicitly states the parameter 'uuid' and its purpose: 'Delete a firewall filter rule by UUID', and instructs to find the UUID. This adds meaning beyond the bare schema, though it doesn't provide format or validation details, which are not needed for a simple UUID.

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

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

The description clearly states the action: 'Delete a firewall filter rule by UUID'. It specifies the resource (firewall firewall rule) and the method (delete), and distinguishes from siblings by mentioning savepoint protection and referencing other tools like opn_list_firewall_rules and opn_confirm_changes.

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

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

The description gives explicit usage guidance: 'Use this when you need to remove an existing MVC firewall rule.' It also instructs to use opn_list_firewall_rules first to find the UUID, and mentions taking a backup if savepoint_support is false, providing clear when-to-use and when-not-to-use scenarios.

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 full burden. It thoroughly discloses the savepoint behavior across OPNsense versions: auto-revert on <26.7 unless confirmed via opn_confirm_changes, and immediate unrevertible changes on 26.7+. It also explains the return value ('revision' and 'result') and warns about potential lockout, making the tool's behavior highly transparent.

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

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

The description is well-structured and every sentence adds value, but it is slightly verbose. The opening sentence is front-loaded, and the version-specific paragraphs are necessary. The line 'Use this when you need to remove an existing NAT rule' is somewhat redundant with the first sentence, but it reinforces usage intent.

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

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

Despite no annotations, the description covers all critical context: purpose, when to use, version-specific behavior, prerequisites, backup safety, and return value. The output schema exists but the description adds clarification for the return keys. The tool's complexity (savepoint behavior, lockout risk) is fully addressed.

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. It does so by explaining that the 'uuid' parameter is the identifier of the NAT rule to delete, and instructs the agent to find it via opn_list_nat_rules. This fully clarifies the meaning and origin of the only parameter.

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

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

The description opens with a specific verb and resource: 'Delete a NAT port forwarding rule by UUID'. This clearly distinguishes it from sibling tools like opn_add_nat_rule and opn_update_nat_rule, and the 'by UUID' qualifier makes the operation precise.

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 to use: 'Use this when you need to remove an existing NAT rule.' It also provides critical usage context: check opn_mcp_info for savepoint support, back up with opn_download_config if needed, and find the UUID via opn_list_nat_rules. This is clear, actionable guidance with sibling-tool references.

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 must carry the burden of disclosing behavior. It describes a lookup operation but does not specify safety, permissions, or whether it modifies state. It is minimal beyond the basic 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?

Three sentences: first states purpose, second gives use cases, third describes return format. No redundant words, 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?

Given the tool's simplicity (2 params, 1 required), the description covers purpose, use cases, and return format. It lacks error behavior or parameter details but is adequate for a diagnostic tool with an output schema (mentioned).

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 should add meaning. It implies that 'server' is for specifying a DNS server, but does not explicitly link to the parameter. 'hostname' is obvious. Adds some value but not enough to fully compensate.

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

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

The description clearly states 'Perform a DNS lookup from the OPNsense firewall' with a specific verb and resource. It also lists use cases that distinguish it from sibling tools like opn_dns_stats or opn_ping, though not explicitly naming them.

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

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

Provides explicit scenarios for use: testing DNS resolution, verifying Unbound, checking a specific DNS server. Does not mention when not to use or alternatives, but the positive guidance is sufficient.

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

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

No annotations provided, so description carries burden. It states returns a dict with fields but lacks details on side effects, auth requirements, or behavior if resolver is unavailable.

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 concise sentences front-loading purpose, use case, and return type with no wasted words.

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

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

For a zero-parameter read-only tool with an output schema, the description adequately covers purpose, usage, and return value.

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?

No parameters exist; schema coverage is 100% (empty). Baseline 4 applies as description adds no parameter meanings, but none are needed.

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

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

The description clearly states 'Get Unbound DNS resolver statistics' with specific metrics (queries, cache hits, uptime), distinguishing it from sibling DNS tools like opn_dns_lookup.

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

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

Provides explicit usage context: 'Use this when you need to check DNS resolver performance, cache hit rates, or troubleshoot DNS resolution issues.' No alternatives or exclusions, but clear 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?

With no annotations provided, the description carries the full burden and does so: it discloses default redaction of secrets, the fail-closed behavior when the config cannot be parsed (refused, never returned raw), and the environment prerequisite OPNSENSE_ALLOW_SENSITIVE=true for include_sensitive. These are exactly the safety facts an agent needs before invoking a config-exfiltration-style 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?

Front-loaded with the one-line purpose, then usage constraint, then safety semantics, then return shape. Every sentence carries distinct information; nothing is restated from the schema or 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?

A single-parameter tool with an output schema and no annotations is fully covered: purpose, alternatives, redaction/refusal behavior, env precondition, and response keys are all present. The return-value sentence is mildly redundant given the output schema but adds error-key detail that aids handling.

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 parameter has no schema description, so the description must compensate — and it does, explaining include_sensitive's default, its interaction with the server env var, and the refusal outcome when the env var is absent. That is meaning well beyond the bare boolean type and default in 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 and resource ('Download OPNsense config.xml backup as raw XML'), including the output format, and explicitly names the sibling tools (opn_scan_config, opn_get_config_section) that serve adjacent purposes. An agent can distinguish this from the section-query siblings without opening any schema.

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

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

Gives an explicit when-to-use constraint ('ONLY when you need a full XML backup for archival purposes') plus a concrete alternative path for the other common case: opn_scan_config then opn_get_config_section. When-not and alternatives are both 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?

With no annotations, the description must disclose behavior. It explains that filter parameters apply substring matches client-side and outlines the return format. However, it omits details like default time range, ordering, or any destructive implications (none expected). The description is adequate but not 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?

The description is concise with three sentences. The first sentence immediately states the purpose, and subsequent sentences add usage context and behavior. Every sentence adds value, and there is no redundancy.

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

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

Given the existence of an output schema, the description adequately explains the return structure (entries list and total count). It covers the key aspects of the tool for typical usage. However, it does not mention potential pagination or default time range, which could enhance completeness.

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

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

Schema description coverage is 0%, so the description must compensate. It states that all filter parameters are optional substring matches applied client-side, which adds meaning beyond the schema. However, it does not describe each parameter individually (e.g., valid values for 'action'), and the general description is somewhat vague.

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

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

The description clearly states 'Get recent firewall log entries (blocked and passed packets)', specifying the verb, resource, and scope. However, it does not explicitly distinguish from sibling tools like opn_pf_states or opn_interface_stats, which could serve similar purposes.

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 provides explicit use cases: 'check what traffic has been blocked or passed, troubleshoot connectivity issues, or audit firewall activity'. However, it lacks guidance on when not to use this tool or alternative tools for similar tasks, such as opn_pf_states for stateful inspection.

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

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

There are no annotations, so the description must carry the full burden of behavioral disclosure. It says the tool is a read-style getter and discloses the return shape ('gateway items including status, loss, and delay fields') plus a concrete envelope quirk, which adds real value, but it omits whether all gateways or only WAN gateways are included, and whether authentication or permissions matter.

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 leads with purpose, then use cases, then the return shape. Each sentence contributes, and there is no filler; even the parenthetical about the array envelope carries information an agent would otherwise have to discover at runtime.

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

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

An output schema exists, so the description need not enumerate return fields, yet it summarises them briefly and explains the envelope fallback. It is complete for a zero-parameter read tool, missing only scope details such as whether only WAN gateways are covered or what an empty result looks like.

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 the baseline is 4. The description correctly implies that no filtering input is required, and its mention of a 'rows'/'rowCount' wrapper clarifies output structure rather than input semantics.

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

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

The description uses a specific verb and resource ('Get gateway status'), then narrows it further with 'including dpinger health checks'. This distinguishes it from siblings such as opn_system_status, opn_interface_stats, and opn_pf_states, 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?

It gives clear use cases (WAN gateways up, latency, packet loss, failover state), so the agent can decide when the tool applies. It stops short of stating exclusions or naming alternatives; for example, it does not say which tool to choose for interface-level versus gateway-level health.

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 behavioral burden and does most of it well: it discloses the implicit config-load side effect, that available sections vary per installation, and that sensitive values are redacted by default unless OPNSENSE_ALLOW_SENSITIVE=true is set server-side. The only gap is that it never states read-only/non-destructive intent outright or what happens on an invalid section name, which matters given the free-form string parameter.

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 and the scan-then-drill workflow are front-loaded, and the section enumeration earns its space by standing in for a missing enum. The 'filter' callout paragraph is also justified, though the description runs slightly long for a two-parameter read tool.

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

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

An output schema exists, so return values need not be spelled out, yet the description still notes the 'section'/'data' shape. Combined with prerequisites, redaction policy, and per-installation section variance, an agent has everything needed to call this correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: it enumerates common section values (system, interfaces, vlans, filter, nat, OPNsense, unbound, dnsmasq, dhcpd, staticroutes, syslog), effectively substituting for the missing enum, and it fully explains include_sensitive including the environment-variable gate. It stops short of saying whether section names are case-sensitive or how unknown names are handled.

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 ('Get a specific configuration section as structured JSON') and immediately scopes it against the sibling opn_scan_config, which is the closest conceptual neighbor. It also explicitly distinguishes the 'filter' section from what opn_list_firewall_rules returns, so an agent can tell exactly what data this tool uniquely exposes.

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 an explicit sequencing rule ('Use this after opn_scan_config to drill into a specific area') plus a concrete when-to-prefer-this case: filter sections holding legacy GUI rules not visible via opn_list_firewall_rules. The auto-load fallback ('If the config hasn't been scanned yet, it will be loaded automatically') removes the only precondition an agent might worry about.

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 must convey behavioral traits. It indicates a read operation ('Get') and lists return fields, implying no side effects. However, it does not disclose permissions, rate limits, or potential errors. The description adds some context beyond the name but lacks depth.

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

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

The description is concise, consisting of three short sentences and a bulleted list. The first sentence states the purpose, followed by usage guidance and return structure. Every sentence adds value without redundancy.

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

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

Given the tool has only one required parameter and an output schema (mentioned but not provided), the description covers the purpose, usage context, prerequisite, and return fields. It doesn't discuss error handling or authentication, but for a straightforward read operation, it is largely complete.

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

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

The sole parameter 'uuid' is not described in the input schema (0% coverage), but the description explicitly states 'by UUID' and instructs to fetch the UUID from 'opn_list_dnsbl first'. This adds significant meaning beyond the raw schema, explaining how to obtain and use the parameter.

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

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

The description clearly states the tool retrieves the full DNSBL configuration for a specific blocklist by UUID. It specifies the action ('Get'), the resource ('DNSBL configuration'), and the identifier needed. It also distinguishes from the sibling tool 'opn_list_dnsbl' by mentioning it as a prerequisite.

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

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

The description explicitly tells when to use the tool: 'when you need to see all available providers and their selection state' and similar. It also instructs to 'Get the UUID from opn_list_dnsbl first,' providing a clear prerequisite. However, it does not explicitly state when not to use or mention alternative tools.

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

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

No annotations are provided, so the description carries full burden. It discloses that changes are not applied until opn_reconfigure_haproxy, recommends testing first, and explains that omitted config fields get defaults. Return format is specified. This is sufficient for a creation tool.

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

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

The description is well-structured with a clear purpose, examples, and notes. It is relatively long but each section adds value. Could be slightly trimmed without losing essential info.

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

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

The description covers the tool's purpose, parameter usage, example configurations, post-creation steps, and return value. Given the complexity of the tool (creating multiple resource types), it is complete and informative.

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%, but the description adds significant value by explaining the config dict usage, providing detailed examples for health checks and IPv6 setups, and listing example fields. However, it does not enumerate valid resource_type 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 explicitly states 'Create a new HAProxy resource' and lists the specific resource types (frontends, backends, servers, etc.), clearly distinguishing the tool from siblings like opn_haproxy_update.

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 provides clear context for when to use the tool, including examples and a note about calling opn_haproxy_configtest before reconfigure. It mentions opn_haproxy_update as an alternative but does not explicitly state when not to use.

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?

Describes internal mechanism ('haproxy -c') and return type (dict with 'status' key). No annotations provided, so description carries burden; could add more detail about error reporting or side effects.

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

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

Five concise sentences with no waste. Front-loaded purpose, then usage, mechanism, and return. Ideal structure.

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 purpose, when to use, how it works, and return format. Output schema exists, so return details are partially covered. Lacks prerequisites or error handling nuances, but sufficient for a simple validation 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?

No parameters. Schema coverage is 100% (empty). Baseline 4 applies per rules.

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?

Clearly states the tool validates HAProxy configuration syntax before applying. Distinguishes from sibling opn_reconfigure_haproxy by explicitly saying 'Use this BEFORE calling opn_reconfigure_haproxy'.

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 advises using before opn_reconfigure_haproxy. Lacks explicit when-not-to-use or alternatives, but the directive is clear and actionable.

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 discloses key behaviors: the deletion is permanent, requires dependency checks, and changes are not applied immediately until reconfigure. It does not detail error handling or side effects, but the essential behavioral traits are covered.

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

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

The description is concise and well-structured. It opens with the main action, then clearly presents dependency warnings, resource types, a reconfigure note, and return value. Every sentence adds necessary information without redundancy.

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

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

Given the tool's complexity (dependencies, deferred application), the description covers the essential context: resource types, deletion order, and reconfigure requirement. It lacks information about error responses or what happens if the resource doesn't exist, but the output schema and basic return dict are mentioned. Overall, it is sufficiently complete for an agent to use the tool correctly.

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

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

The input schema has 0% description coverage, but the description adds value by enumerating valid resource types (frontends, backends, servers, etc.). However, the uuid parameter is not described beyond being a UUID. The list of resource types helps understand the 'resource_type' parameter, but it is not explicitly linked as a parameter value list.

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

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

The description clearly states the action: 'Delete a HAProxy resource by UUID.' It specifies the resource type (HAProxy) and identifier (UUID), and lists the specific resource types that can be deleted. This distinguishes it from other delete tools 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?

The description provides critical usage guidelines, including dependency order (e.g., delete servers before backends) and the need to call opn_reconfigure_haproxy to apply changes. It does not explicitly compare to alternative tools (e.g., opn_haproxy_update), but the context is clear enough for the agent to use it appropriately.

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

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

Describes return format ('dict with the resource type as key containing all field values') and mentions included fields (SSL, tuning, persistence, linked resources). No annotation provided, but read behavior is implied; could mention idempotence or lack of side effects.

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

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

Description is 7 sentences, front-loaded with purpose, and every sentence provides value without redundancy.

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

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

Tool has two straightforward params and an output schema; description covers resource types and return format. Lacks mention of error handling or authentication, but context is sufficient for a get 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 description must compensate. It lists resource types in text but does not explain the 'uuid' parameter or provide value constraints beyond the list. Adds some meaning but insufficient detail.

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?

Clearly states 'Get detailed configuration for a specific HAProxy resource' and lists resource types, distinguishing from sibling tools like add/delete/update/search/status.

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 'Use this to inspect all fields of a single resource before modifying it', providing clear context for when to use, though it does not explicitly exclude other use cases.

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 provides significant behavioral info: it notes pagination, lists resource type fields, and states return format ('dict with rows and rowCount'). However, it doesn't explain search semantics (e.g., exact match vs substring) or pagination details (e.g., offset or cursor).

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

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

The description is well-structured: a clear purpose sentence, followed by a bullet list of resource types with key fields, and a return format statement. Every sentence adds value, no redundancy, and it is front-loaded with the main purpose.

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

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

Given the tool's complexity (multiple resource types) and low schema coverage, the description is incomplete. It lacks search behavior details (e.g., how the 'search' parameter works) and pagination mechanics (e.g., page size limits or pagination tokens). The return format is described, but crucial usage context 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 description must compensate. It thoroughly explains 'resource_type' by listing all values and key fields. However, 'search' and 'limit' are only mentioned by default value and type; search behavior and limit maximum are not described. This leaves gaps beyond the schema.

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

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

The description clearly states 'Search HAProxy resources by type' and lists all resource types and their key fields. It differentiates from sibling tools like opn_haproxy_get, opn_haproxy_add, etc., by focusing on paginated search.

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

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

The description says 'Use this to list and search any HAProxy resource. All resource types use the same paginated search pattern.' This implies usage context but lacks explicit guidance on when not to use (e.g., for single resource retrieval) or alternative tools.

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

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

No annotations are provided, so the description must disclose behavioral traits. It states the tool is read-only (get) and lists a prerequisite, but does not mention potential errors, data freshness, or authorization needs. This is adequate but not thorough.

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 four sentences, each serving a distinct purpose: purpose, usage, prerequisite, and return type. No unnecessary words, well-structured, and easy to parse.

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 status tool with no parameters and an existing output schema, the description covers all essential aspects: what it does, when to use, a key prerequisite, and return type. No additional details are needed for an AI agent to correctly invoke 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?

There are no input parameters, so the description has no additional parameter info to provide. According to rules, 0 parameters yields a baseline of 4.

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

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

The description clearly states the tool retrieves HAProxy load balancer status and backend health, using a specific verb and resource. It distinguishes from sibling HAProxy tools like configuration or search by focusing on status and health.

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 provides a clear use case (checking status, availability, statistics) and a prerequisite (requires os-haproxy plugin). However, it does not explicitly mention when not to use it or suggest alternatives among siblings.

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

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

The description fully discloses that changes are not applied until opn_reconfigure_haproxy is called, that configtest should be performed first, and the return format. It also explains the config parameter behavior (partial updates) and enable/disable pattern. No annotations exist to contradict.

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

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

The description is concise, well-structured, and front-loaded. Each sentence serves a distinct purpose: purpose, usage, config pattern, resource types, and workflow notes. No wasted words.

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

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

Given the tool's complexity (update on multiple HAProxy resource types) and absence of output schema, the description provides all necessary context: purpose, parameters, allowed values, workflow dependencies, and return format. It enables correct invocation without missing critical 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?

With 0% schema description coverage, the description adds essential meaning: lists valid resource_type values, explains config as a partial update object with enable/disable example, and implies uuid as identifier. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states 'Update an existing HAProxy resource' and lists specific resource types, distinguishing it from sibling tools like opn_haproxy_add, opn_haproxy_delete, etc.

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 states when to use (modify any field on an existing resource) and provides critical workflow guidance (call configtest first, then reconfigure). However, it does not explicitly mention when not to use or compare to alternatives.

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

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

No annotations are supplied, so the description carries the full burden. 'Get' implies a safe read and the return shape is disclosed, but it says nothing about permissions, data freshness/sampling window, or whether counters are cumulative vs. rate-based – details that matter for interpreting traffic stats.

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 verb and resource, with a separate 'Returns:' line. Slightly duplicative given an output schema exists, but nothing is wasted.

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

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

For a parameterless read tool with an output schema, the description covers purpose, usage and return shape adequately. The only meaningful gap is behavioral context around what the counters represent (interval, reset behavior), which annotations would normally have covered.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the description misleads about inputs, and it correctly implies no filtering arguments exist.

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

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

States a specific verb and resource ('Get per-interface traffic statistics') and enumerates the counters returned (bytes in/out, packets, errors). An agent can distinguish it from siblings like opn_pf_states or opn_system_status, though the description never explicitly names those alternatives.

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

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

Gives concrete triggers: 'when you need to see network utilization, check for interface errors, or compare traffic across interfaces.' That is clear usage context, but there are no explicit exclusions or pointers to sibling tools for adjacent needs.

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

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

No annotations provided, so description covers behavior. It discloses the two phases, return structure, and strongSwan dependency. Lacks details on error handling or empty status, but sufficient for a read-only status 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?

Concise and well-structured: first sentence states purpose, then usage guidance, then technical details and return format. No wasted words.

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

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

Given no parameters and presence of output schema (described), the description fully covers the tool's behavior, prerequisites, and return value, leaving no gaps.

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

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

Input schema is empty (0 parameters), so description does not need to add parameter info. Baseline for 0 params is 4.

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

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

The description clearly states 'Get IPsec VPN tunnel status (IKE and ESP phases)' and distinguishes from sibling VPN status tools like opn_openvpn_status and opn_wireguard_status.

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 when to use: 'check IPsec site-to-site tunnel health, see connected peers, or troubleshoot VPN connectivity' and notes prerequisite 'Requires IPsec to be configured'.

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 provided, so description carries full burden. It describes the output structure and that it's a read operation. No contradictions; could mention privilege requirements but not needed for this simple query.

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 sentences, each serving a distinct purpose: purpose, usage guidance, return format. No wasted words, 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?

Given no parameters and an output schema, the description covers the essential: what tool does, when to use, and what it returns. Could mention error behavior but not necessary for this simple status 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?

No parameters. Description correctly indicates no parameters needed. Baseline for zero parameters is 4, and description adds no misleading info.

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

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

The description clearly states it retrieves IPv6 configuration and address status for all interfaces, with a specific verb and resource. It distinguishes from siblings like opn_interface_stats or opn_gateway_status by focusing on IPv6.

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

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

Provides explicit guidance: 'Use this when you need a quick overview of which interfaces have IPv6 configured...' It doesn't mention when not to use or alternatives, but the use case is clear.

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

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

No annotations are provided, so the description carries the burden. It states it returns a dict with 'rows' and 'rowCount', which implies no side effects for a list operation. However, it does not explicitly state that the operation is read-only or safe, nor does it disclose authentication needs or rate limits. The description is adequate but not fully transparent.

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

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

The description is two sentences plus a note and return format. It is clear and front-loaded with the core purpose. While it could be slightly more concise by integrating the usage guidance, it is not verbose and 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?

Given the presence of an output schema (though not shown), the description provides a summary of the return type. It mentions the required plugin, which is important context. However, it does not explain the effect of the 'search' and 'limit' parameters, nor does it mention potential pagination or other caveats. The description is adequate but incomplete regarding parameter behavior.

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%, meaning the description does not explain the parameters 'search' and 'limit'. The description adds no meaning beyond what the input schema already provides. This is a significant gap, as the agent must infer parameter usage from the schema alone.

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

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

The description explicitly states it lists ACME certificates and their status, and explains what information can be obtained (expiry, renewal, domains). It clearly differentiates from sibling tools, as no other sibling is specifically for ACME certificate listing.

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 provides clear usage guidance: 'Use this when you need to check certificate expiry dates, renewal status, or which domains have ACME certificates configured.' It also mentions a prerequisite (ACME client plugin required). There are no explicit exclusions or alternatives, but given the sibling tools list, this is the only tool for this purpose.

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 burden. It states the return format (dict with 'rows' and 'rowCount') and implies a read-only operation. However, it does not disclose any other behavioral traits like permissions or side effects. This is adequate but not exceptional.

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 three sentences: one for purpose, one for usage, and one for return format. No wasted words, front-loaded with key information.

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

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

Despite missing parameter explanations, the description covers purpose, usage, and return format. The presence of an output schema (implied) reduces the need to explain return values. The tool is simple, and the description is mostly 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%, meaning no parameter descriptions in the schema. The description does not explain the 'search' and 'limit' parameters, failing to compensate for the low coverage. The parameters remain undocumented.

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

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

The description clearly states the verb 'List', the resource 'scheduled cron jobs', and the context 'in OPNsense'. It distinguishes this tool from sibling list tools by specifying it lists cron jobs specifically.

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

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

The description explicitly says 'Use this when you need to check what scheduled tasks are configured, their frequency, or which commands they run.' This provides clear usage context, though it does not mention when not to use it or list alternatives.

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

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

No annotations provided, so description carries full burden. Explains return format (dict with rows/rowCount) and important edge case (IPv6 silent failure). Good transparency.

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

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

Well-structured with clear first sentence, bulleted key fields, and separate notes. Slightly verbose but efficient overall.

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 return structure and important context (IPv6, plugin requirement). Lacks parameter descriptions. Balanced for a list tool with output schema.

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 0%; description does not explain 'search' and 'limit' parameters. Missing crucial guidance on filtering and pagination.

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?

Clearly states 'List Dynamic DNS (DDNS) accounts and their update status' – specific verb+resource, distinguishes from add/delete/update siblings.

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

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

Mentions 'Use this to check which hostnames have DDNS configured' and notes prerequisite (os-ddclient plugin), but does not explicitly state when not to use it. Adequate given sibling clarity.

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 exist, so the description carries the full burden, and it does disclose meaningful behavior: the read-only listing nature, the legacy/deprecation status of the backend, and the prerequisite backend check. What it omits is the failure behavior when ISC DHCP is not installed or not running (error vs. empty list), which is the main remaining unknown for a mutation-free call.

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, then backend caveat, then prerequisite, then return shape — a sensible ordering with no filler. The trailing parenthetical about a bare array arriving in a 'rows'/'rowCount' envelope is slightly awkwardly worded and partly overlaps the existing output schema, but it carries real value.

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

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

Given zero parameters and an existing output schema, the description covers what an agent needs to select the tool and route to the right backend sibling. The one gap is the missing statement of what the call returns or errors with when the ISC DHCP plugin is absent, which would fully close the loop on the deprecation warning it raises.

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 spends no words on 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?

States a specific verb and resource ("List current DHCPv4 leases") plus the exact backend it targets (ISC DHCP server / os-isc-dhcp plugin). This cleanly separates it from the sibling lease lister opn_list_kea_leases and opn_list_dnsmasq_leases without the agent needing to open any schema.

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

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

Explicitly states when to use it (the instance runs the ISC DHCP plugin), warns that ISC DHCP is legacy and most 26.x systems use dnsmasq or Kea, and prescribes a concrete prerequisite action: call opn_scan_config first to determine the active backend. That is when-to-use, when-not-to-use, and the alternative-selection path all in one place.

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 full burden. It only describes the return format but does not mention behavioral aspects such as read-only nature, authentication requirements, or performance implications. The tool is likely safe, but this is not disclosed.

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 three sentences, each adding value: purpose, usage scenario, alternative tool, and return structure. It is front-loaded with the key idea and contains no redundant information.

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

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

For a listing tool with two optional parameters, the description covers the core purpose, usage context, and return structure. It lacks parameter details but otherwise provides sufficient context for an AI agent to use the tool correctly.

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

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

The input schema has two parameters (search, limit) with defaults but no descriptions. The description does not explain their meaning or usage, leaving a gap especially given 0% schema description coverage. No per-parameter guidance is provided.

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

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

The description clearly states it lists DNSBL configurations with providers and status. It distinguishes from the sibling tool opn_get_dnsbl by noting that the latter provides full details, making the purpose and differentiation explicit.

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 specifies when to use this tool (to see configured blocklists, active providers, allowlist/blocklist entries) and provides an alternative (opn_get_dnsbl for full details). It does not explicitly mention when not to use it, but the context is clear enough.

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

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

With no annotations, the description discloses the return format (dict with 'rows' and 'rowCount'), indicating it's a read operation. However, it does not mention any potential side effects, permissions, or limitations. This is adequate for a simple listing tool but lacks depth.

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

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

The description is concise, consisting of three sentences that are front-loaded with the core purpose. Each sentence adds value: function, use case, and return structure. No unnecessary words.

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

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

Given the tool's simplicity (list with two optional parameters) and the presence of an output schema, the description covers the main aspects: what it lists, when to use, and what it returns. The missing parameter explanations are a minor gap in an otherwise complete description.

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

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

The input schema has two parameters (search, limit) with 0% description coverage in the schema. The description provides no explanation of these parameters, leaving the agent to infer their meaning from the schema types and defaults. This is a significant 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 clearly states the tool lists 'Unbound DNS forward zones' and defines them as 'domain-specific DNS servers'. It uses specific verb ('List') and resource ('DNS forward zones'), distinguishing it from sibling list tools like opn_list_dns_overrides or opn_dns_lookup.

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

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

The description explicitly says 'Use this when you need to check which domains are forwarded to specific upstream DNS servers or DNS-over-TLS resolvers'. This provides clear context for when to use, though it does not mention alternatives or when not to use.

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