OPNsense MCP Server
Server Quality Checklist
Latest release: v0.4.1
- Disambiguation4/5
Most tools have clearly distinct purposes (e.g., list vs add vs update vs delete for DNS overrides, DHCP ranges, firewall rules). Some overlap exists between opn_haproxy_search and opn_haproxy_get (search vs get details) and between opn_list_dnsbl and opn_get_dnsbl, but descriptions clarify the use cases. The distinction between legacy and MVC firewall rules is well-documented, reducing ambiguity.
Naming Consistency4/5Tools primarily follow the verb_noun pattern with 'opn' prefix (list_, add_, update_, delete_, get_, set_, reconfigure_, etc.), which is consistent and predictable. Minor deviations like 'opn_ping', 'opn_traceroute', 'opn_dns_lookup', and 'opn_security_audit' do not follow the verb_noun pattern as strictly, but they are still clear and distinct.
Tool Count2/5With 81 tools, the server is heavily over-scoped. While OPNsense is a complex system, this number far exceeds the typical range for a coherent MCP server, making it difficult for agents to discover and select the right tool efficiently. Many tools are for niche plugins (HAProxy, CrowdSec, mDNS Repeater) that could be separate optional servers.
Completeness4/5The server provides comprehensive CRUD operations for core domains: firewall rules, aliases, NAT rules, DNS overrides, dnsmasq ranges, DDNS accounts, and HAProxy resources. It also covers status, diagnostics, and even security audit. Minor gaps exist like no explicit tool to edit system settings or manage users, but the main firewall management workflows are well covered.
Average 4.3/5 across 79 of 81 tools scored. Lowest: 3.4/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 2 community issues answered or closed in the last 6 months
- 3 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
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 tool returns a dict with 'rows' and 'rowCount', indicating the action is read-only. However, it does not explicitly state that the operation is non-destructive or describe any side effects, which is acceptable for a listing tool but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of three sentences that front-load the purpose, provide usage context, and mention the return format. Every sentence adds value without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and the presence of an output schema, the description covers the core purpose and usage context. However, it lacks parameter semantics, which are important for effective use. This gap reduces completeness, making it adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (search, limit) with default values, but schema description coverage is 0%. The description does not explain what these parameters do (e.g., search filters by hostname, limit controls page size). Since it fails to compensate for the lack of schema descriptions, the score is low.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Unbound DNS host overrides (local DNS records). It uses a specific verb ('List') and resource ('DNS host overrides'). However, it does not explicitly differentiate from sibling tools like opn_list_dns_forwards, but the name and context make the distinction clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 see which hostnames are overridden to specific IP addresses', providing clear context for when to use the tool. It does not mention when not to use it or provide alternatives, but the guidance is direct and adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Description mentions tracing path but does not disclose potential side effects (e.g., sending packets), permissions required, or that it is a read-only operation. Lacks behavioral context beyond purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is extremely concise: two sentences on purpose and usage, plus a clear return format. No extraneous content, front-loaded with actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and low schema coverage, the description provides general usage context and return structure but fails to document parameter options (protocol, ip_version) that are crucial for correct invocation. Output schema mitigates return understanding but does not compensate for parameter gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, and description fails to explain parameters (host, protocol, ip_version). No details on valid protocol values (e.g., ICMP, UDP, TCP) or IP versions, leaving the agent without guidance on parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Trace the network path' with specific verb and resource, and distinguishes from sibling tool opn_ping by focusing on hop-by-hop visualization of routing issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: diagnosing routing issues, packet drops, or visualizing network hops. However, it does not mention when not to use or suggest alternatives like opn_ping for simple reachability tests.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that it lists both DHCPv4 and DHCPv6, and that IPv6 leases appear alongside IPv4. It also describes the return format (dict with 'rows' and 'rowCount'). However, it lacks details on permissions, rate limits, or any side effects. Overall adequate for a read-only list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is six sentences, front-loaded with the main purpose. Each sentence adds value (purpose, usage context, IPv6 handling, output format). It is concise but could be improved by including parameter descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two optional parameters with no descriptions and no annotations, the description is incomplete. It adequately describes the output but fails to explain input parameters. For a simple list tool, it is partially complete but has a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for both parameters ('search' and 'limit'). The description provides no explanation of these parameters or their expected values, leaving the agent to rely solely on the schema defaults, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'DHCPv4 and DHCPv6 leases from the dnsmasq DNS/DHCP server'. It distinguishes from sibling tools like opn_list_kea_leases by specifying dnsmasq and referencing opn_scan_config to check the backend.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use this tool ('when the OPNsense instance uses dnsmasq for DHCP') and advises to check the backend first via opn_scan_config. It implies alternatives (kea), though it doesn't explicitly list 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It mentions the return format (dict with rows/rowCount) and version requirement (24.7+). However, it omits parameter behavior, edge cases, or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loaded with purpose. The third sentence adds background about Kea being a modern replacement, which is slightly extraneous but not harmful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, it covers usage context and return format but fails to document parameters. The existence of an output schema helps, but missing parameter semantics leaves a gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description provides no information about the two parameters (search, limit). The agent is left without any guidance on how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'current DHCPv4 leases from the Kea DHCP server'. It distinguishes this tool from siblings like opn_list_dhcp_leases and opn_list_dnsmasq_leases by specifying the Kea backend.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance: 'Use this when the OPNsense instance uses Kea for DHCP' and suggests using opn_scan_config first to check the backend. It also mentions Kea is for HA setups, but does not explicitly exclude other backends.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 the return format (dict with 'rows' and 'rowCount') but does not mention permissions, idempotency, or 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is four sentences with no fluff. First sentence gives purpose, second gives usage, third clarifies scope, last describes output. Efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the description mentions return format, it covers that well. However, input parameters are not explained, which is a gap for a tool with 0% schema description coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description fails to explain the 'search' and 'limit' parameters, leaving the agent unsure of their purpose and syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List configured static routes' and provides specific use cases. It distinguishes itself from sibling list tools by specifying the resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use the tool and clarifies it does not show the full kernel routing table, providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose4/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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 describes the return format (dict with 'rows' and 'rowCount'), but does not disclose whether the tool is read-only, requires permissions, or has side effects. Adequate for a query tool but missing safety disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no redundancy. First sentence states purpose, second gives usage context, third specifies return format. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and two undocumented parameters, the description is incomplete. It covers the purpose and return structure, but the lack of parameter documentation and behavioral details makes it only partially complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description fails to mention either parameter ('search' or 'limit'). The agent receives no guidance on how to use these parameters, which is a critical omission.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries the active PF state table, with a specific verb and resource. It is distinguishable from sibling tools like opn_firewall_log and opn_list_firewall_rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases: seeing active connections, debugging NAT, identifying hosts. It does not explicitly mention when not to use or alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness4/5Is 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.
Completeness3/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters1/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters1/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It notes that both IPv4 and IPv6 ranges appear in same list, lists key fields, and describes return format (dict with 'rows' and 'rowCount'). However, it omits pagination behavior (limit parameter) and search filtering details, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is about 80 words in two paragraphs. Purpose is front-loaded, and key details follow. Some redundancy ('both DHCPv4 and DHCPv6' appears twice) but overall efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of an output schema, the description covers the output structure, key fields, and prerequisite. However, missing parameter explanations slightly reduce completeness. Still adequate for a list tool with existing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It only mentions 'search' and 'limit' but does not describe their semantics (e.g., what search filters, how limit controls pagination). The listed key fields are for the output, not the input parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List dnsmasq DHCP ranges (both DHCPv4 and DHCPv6 with RA config).' Verb 'list' and resource 'dnsmasq DHCP ranges' are explicit, and the description distinguishes from sibling tools like opn_list_dhcp_leases by specifying ranges (pools) versus leases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: 'Use this to see configured DHCP address pools and Router Advertisement settings for each interface.' Also mentions prerequisite ('Requires the dnsmasq DNS/DHCP server'). Does not explicitly state when not to use or name alternative tools, but the context is sufficient for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses return format (dict with 'rows' and 'rowCount'). Does not detail side effects (read-only), pagination, or authentication. Adequate but could elaborate on search behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise: 2 sentences including return value. Main action is front-loaded. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, description still includes return structure, which is helpful. However, it lacks parameter behavior details (e.g., search matching, limit default). Adequate for a simple list tool but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and description does not explain the 'search' or 'limit' parameters. Only implies search functionality via 'what IP addresses/networks they resolve to.' Fails to compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List firewall alias definitions' with specific verb and resource, and lists types (IP lists, port groups, GeoIP, URLs). Differentiated from sibling tools like opn_list_firewall_categories by focusing on aliases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'when you need to see which aliases are defined, their types, or what IP addresses/networks they resolve to.' Does not mention when not to use or alternatives, but context is clear for a list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It discloses the return structure (dict with 'rows' and 'rowCount') but does not mention safety (read-only), permissions, or potential performance characteristics. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with the purpose, followed by usage guidance and return format. No redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the description covers return structure and usage scenarios, but lacks parameter explanations. Given the existence of an output schema (which we know but not shown), the return description is redundant but not harmful. Overall, incomplete due to missing parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does 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 fails to explain the 'search' and 'limit' parameters, their purpose, or how they affect behavior. No value added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'firewall rule categories', and the context of 'check their names and colors' or 'find category UUIDs' distinguishes it from sibling tools like add/delete or list rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'when you need to see which categories exist, check their names and colors, or find category UUIDs for assigning to rules.' This provides clear usage context and implicitly differentiates from alternative operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states it returns a dict with fields, but does not explicitly state it is read-only or non-destructive. However, the nature of a status check implies safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a return statement, with no wasted words. It is front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters and no annotations. The description covers the return structure (dict with status, loss, delay). It is complete enough for a status check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%. The description adds no parameter info, which is appropriate. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get gateway status including dpinger health checks' with a specific verb and resource. It implies focus on WAN gateways and failover, distinguishing it from other status tools like opn_ipsec_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use: 'Use this when you need to check if WAN gateways are up, their latency, packet loss, or failover state.' It provides clear context, though it does not mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness3/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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 the return format (dict with 'rows' and 'rowCount') and implies a read-only operation. It does not mention auth or rate limits, but for a list tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three brief sentences: purpose, usage, return format. No unnecessary words, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema, the description covers the purpose and return structure. However, the lack of parameter explanations reduces completeness given the low schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does 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 parameters (search, limit). The agent has no guidance on how to use them, which is a significant gap for a tool with two optional parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists system services and their running status, with a specific verb and resource. It distinguishes from sibling list tools (e.g., opn_list_dhcp_leases) by targeting system services.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'when you need to check which services are running, stopped, or available.' It does not provide when-not-to-use or alternatives, but the context of sibling tools helps differentiate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 describes the return structure but does not explicitly state that the tool is read-only or has no side effects. For a status tool, this is adequate but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loads the purpose, and contains no redundant words. Every sentence provides necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an existing output schema, the description adequately explains the return values and notes the requirement that OpenVPN must be configured. It lacks details on error conditions or real-time nature but is sufficient for a status tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With no parameters, schema coverage is 100%, giving a baseline of 3. The description adds value by explaining the return format, but this is more about output than parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get OpenVPN connection status' and lists the components (instances, sessions, routes). Among sibling tools like opn_ipsec_status and opn_wireguard_status, it explicitly names OpenVPN, making it distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios: 'when you need to check OpenVPN server/client status, see connected clients, active VPN routes, or troubleshoot OpenVPN tunnels.' It does not mention when not to use it or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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 transparently discloses that only MVC API rules are returned and legacy rules are invisible, even noting that a result of 0 does not mean no rules exist. It also describes the return format as dict with 'rows' and 'rowCount'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear one-line purpose, an important note in a separate paragraph, and a usage line. Every sentence adds value, and it is front-loaded with the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters and no annotations, the description covers the essential context: scope, limitation (legacy rules excluded), and return format. The only gap is the lack of parameter explanations, which prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (search and limit) with no descriptions (0% coverage). The description does not explain these parameters at all, failing to add meaning beyond what the schema provides. With zero schema coverage, the description must compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists firewall filter rules configured via the MVC API, distinguishing it from legacy rules. The verb 'List', resource 'firewall filter rules', and scope are specific, and it differentiates from sibling tools like opn_list_nat_rules and opn_list_firewall_aliases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 inspect MVC-managed firewall filter rules.' It warns that legacy rules are not included, providing important context for when not to rely on this tool. However, it does not name alternative tools for legacy rules, so a slight deduction for lack of explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must cover behavioral traits. It mentions automatic loading if unscanned and lists common sections, but does not explicitly state it is non-destructive or disclose any side effects, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with the main action, and well-structured with clear sections. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description adequately covers usage flow, return type (dict with 'section' and 'data'), and context. Lacks explanation for one parameter but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'section' parameter by listing common values and highlighting the 'filter' section. However, it does not explain the 'include_sensitive' parameter, despite 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves a specific config section as structured JSON, and distinguishes itself from siblings like opn_scan_config and opn_list_firewall_rules by explaining its role post-scan and highlighting the 'filter' section for legacy rules not visible elsewhere.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance to use after opn_scan_config and mentions auto-loading if not scanned. But lacks explicit when-not-to-use or comparison to other config retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses that the ping runs on the firewall (not locally) and mentions the return format (dict with loss and RTT stats). No contradictory information. It lacks details on side effects or permissions, but for a ping tool, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: four sentences, no unnecessary words. The purpose is front-loaded, and each sentence adds value (purpose, usage, execution context, return info).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters, no nested objects, output schema present), the description is reasonably complete. It covers purpose, usage, and return format. It could mention error handling or timeout behavior, but for a ping tool this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), so the description should compensate. While 'host' is implicitly clear from the purpose, the 'count' parameter is not described. The description does not add meaning beyond the schema. Baseline 3 due to low coverage, and the description only partially addresses the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Ping a host from the OPNsense firewall to test connectivity.' The verb and resource are specific, and it distinguishes from sibling tools like opn_traceroute and 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios: 'Use this when you need to check if a host is reachable from the firewall, measure round-trip latency, or diagnose network connectivity issues.' It also notes that the ping runs on the firewall itself, which is important context. However, it does not mention when not to use or suggesting alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Only the parameters you provide are changed; all other settings are preserved' and 'Changes are applied immediately,' which are useful. However, it omits details like authentication requirements, concurrency behavior, or rollback, leaving gaps for a 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose line, usage guidance, pre-requisite, then parameter list. It is clear and concise, though the parameter list is lengthy. Every sentence serves a purpose with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters with 1 required and the mention of output keys ('result', 'dnsbl_status', 'service_status'), the description covers main aspects. However, it does not explain error conditions or what the 'service_status' field indicates, leaving minor gaps for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 provides a bullet list explaining each parameter (e.g., 'uuid: blocklist UUID from opn_list_dnsbl', 'enabled: enable/disable this blocklist'), adding clear meaning beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a DNSBL blocklist configuration (read-modify-write).' It uses a specific verb ('Update') and identifies the resource ('DNSBL blocklist configuration'), distinguishing it from sibling tools like opn_list_dnsbl (list) and opn_get_dnsbl (get).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs 'Use this when you need to change DNSBL settings' and provides a pre-requisite: 'Get the UUID from opn_list_dnsbl first.' However, it does not mention when not to use it or compare with sibling tools like opn_add_dnsbl_allowlist for single entry changes, missing exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses that only MVC-managed NAT rules are returned, not legacy ones. It also describes return format (dict with 'rows' and 'rowCount'). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, front-loaded with purpose, and each sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers scope, return format, and provides alternative for legacy rules. Missing parameter semantics reduces completeness slightly, but output schema exists and overall information is sufficient for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet description does not explain the parameters 'search' or 'limit'. It does not add meaning beyond the schema's type and default values. This is a significant gap for effective use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists NAT port forwarding (DNAT) rules, using specific verb and resource. It distinguishes from sibling opn_get_config_section('nat') which returns all NAT configuration including legacy rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (seeing forwarded ports, checking config, troubleshooting) and when not to use (legacy rules not shown), providing alternative opn_get_config_section('nat').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It mentions requiring the dnsmasq server and returning a status dict, but omits details like whether the service is restarted, potential downtime, or error conditions. More transparency on side effects would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences plus two notes, all front-loaded with the main action. Every sentence adds value: purpose, usage context, exception, prerequisite, return info. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params) and presence of an output schema, the description covers the core: action, usage context, prerequisite, and return format. It does not explain 'pending changes' or failure modes, but is adequate for a no-param tool with good sibling differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters with 100% coverage (trivially). No parameter documentation needed; baseline 4 applies as per rules. Description adds no param info, but none is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies pending dnsmasq configuration changes, explicitly naming the resource and action. It differentiates from siblings like opn_add_dnsmasq_range by noting auto-reconfiguration, and from other reconfigure tools by specifying dnsmasq.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use: after manual edits. Also states when not needed: opn_add_dnsmasq_range auto-reconfigures, so only for manual edits or troubleshooting. This clear guidance helps avoid misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains toggle behavior ('flips the current state'), notes no savepoint protection, and describes return format. Lacks details on side effects (e.g., immediate effect vs. apply) and error handling, but adequate for a simple toggle.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Six sentences, each with distinct value: purpose, usage context, behavior, savepoint note, prerequisite, and return value. No redundancy or fluff; front-loaded with core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, behavior, prerequisite, and output. Missing explicit error scenarios or confirmation of immediate effect, but sufficiently complete for a single-parameter toggle tool with no output schema provided in structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage for the uuid parameter. Description compensates by explaining how to obtain the UUID ('Use opn_list_firewall_aliases first'). While it doesn't specify format or constraints, the guidance is valuable and clarifies the parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb+resource: 'Toggle a firewall alias's enabled/disabled state.' It uniquely identifies the tool's function among siblings (e.g., opn_toggle_firewall_rule for rules, other alias tools for add/delete/update).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use: 'temporarily disable an alias without deleting it, or re-enable a previously disabled alias.' Includes a prerequisite: 'Use opn_list_firewall_aliases first to find the UUID.' Does not explicitly mention when not to use, but context implies alternatives for other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Discloses immediate application (Unbound reconfigured), preservation of non-provided parameters, non-revertability, and return structure. Does not cover error handling or authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: header, usage context, immediate effect warning, parameter list, return info. Each sentence adds value. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 params with 0% schema coverage, description covers parameters, usage, and return. Lacks error cases (e.g., missing UUID) and explicit mention of override type. Good overall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. Lists all 6 parameters with explanations and examples (e.g., 'e.g. myserver', 'IPv4 or IPv6'). Adds meaning beyond bare schema types. Could improve with format constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an Unbound DNS host override by UUID', specifying the verb (update), resource (DNS host override), and method (by UUID). It distinguishes from sibling tools like add and delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (to change properties), recommends using opn_list_dns_overrides first to get UUID, and warns that changes cannot be auto-reverted. Lacks mention of alternatives like add/delete but is clear overall.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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 the tool returns a dict with fields (ip, mac, intf, hostname). It does not describe side effects, authentication, or rate limits, but for a simple read-only tool with no parameters, this is acceptable. The description gives sufficient behavioral context for an agent to understand the output format, but could mention if the data is live or cached.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences and a one-line output note. It is front-loaded with the core purpose, followed by usage scenarios and return format. Every word earns its place, with no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no side effects) and the presence of an output schema, the description is complete. It explains the tool's function, when to use it, and the structure of the returned data. No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100% (since no params exist). According to guidelines, baseline for 0 parameters is 4. The description adds no parameter-specific information because there are none, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the ARP table showing IP-to-MAC address mappings,' using a specific verb and resource. It distinguishes from sibling tools like opn_ndp_table (IPv6 NDP) by focusing on ARP table, which is IPv4-specific. The description provides a precise and unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'when you need to find which MAC address is associated with an IP, identify devices on a network segment, or troubleshoot connectivity.' It does not explicitly mention when not to use or provide alternatives, but the context of sibling tools (e.g., opn_ndp_table for IPv6) provides implicit guidance. The usage guidance is clear and helpful but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure — and it excels. It thoroughly documents the tri-state 'savepoint_support' field, including the upstream 26.7+ version change, that false means changes are 'immediate and permanent', and that null means no write has probed it yet. This kind of nuanced runtime behavior is precisely the contextual value an agent needs and could not infer from the schema alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the one-sentence purpose, followed by practical usage context, then return-field details. Every clause adds value — the savepoint_support explanation in particular earns its length. It loses one point for the final sentence being a slight run-on, but overall it is dense with relevant information and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter introspection tool, this description is thorough: it documents the purpose, the return fields, and the subtle version-dependent behavior. It could note explicitly that this is a safe read-only operation, but the content strongly implies it and the behavior documentation is more than sufficient for an agent to use this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is trivially 100%, so there is nothing parameter-related to explain. Per the rubric, 0 params earns a baseline 4. The description goes beyond this baseline by documenting the return dict's keys and their semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get MCP server version and runtime configuration' — a specific verb+resource that precisely states what the tool does. It clearly distinguishes this tool from the ~85 sibling operations by scoping it to the MCP server's own metadata (version, write mode, API version) rather than firewall or system state. The name 'opn_mcp_info' is fully and usefully expanded upon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use this to check...' explicitly enumerates the concrete scenarios (checking version, write mode, API version, savepoint protection) which tells the agent when to invoke this tool. It provides clear context but does not explicitly name alternatives or state when not to use it, which would push it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It explains the tool retrieves status and configuration, mentions the plugin requirement, and outlines return fields. It implies read-only behavior but does not explicitly state it is non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence serves a purpose: purpose, usage, background, prerequisites, and return format. It is well-structured and front-loaded with the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter status tool with an output schema, the description covers necessary context: what it does, when to use it, prerequisites, and return fields. It is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, baseline is 4. The description does not need to add param meaning, but it compensates by describing the return value structure, which aligns with the existing output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get mDNS Repeater service status and configuration' which clearly identifies the verb and resource. It distinguishes itself from sibling tools like 'opn_configure_mdns_repeater' by focusing on status retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this to check if...' and lists conditions, providing a clear scenario. It also notes the prerequisite plugin. However, it does not explicitly contrast with alternatives like the configure tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that after update the service is automatically reconfigured and changes take effect immediately. It also explains that only provided parameters are changed. No mention of permissions or error handling, but the behavioral impact is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: opening statement, usage note, parameter list, return info. The parameter list is somewhat lengthy but each entry is necessary. Conciseness could be improved by grouping optional params, but overall it's readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 params, no annotations, update operation), the description is thorough. It covers partial update semantics, service reconfiguration, use of UUID, and return value. Only minor gaps like error handling, but sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 9 parameters are listed with explanations and examples (e.g., 'lease_time: lease duration (e.g. '24h', '1h')'). Since the schema has no descriptions, the description fully compensates with meaningful semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a dnsmasq DHCP range by UUID and apply the configuration.' It specifies the verb (update), resource (dnsmasq DHCP range), and distinguishes from siblings like add and delete by focusing on change.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when you need to change...' and advises to 'Use opn_list_dnsmasq_ranges first to find the UUID.' It mentions partial updates ('Only parameters you provide are changed'). However, it does not explicitly state when not to use it or compare to related tools like opn_reconfigure_dnsmasq.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return type (dict) and key fields (endpoints, transfer stats). Requires plugin is noted. No annotations, so description carries full burden; it sufficiently conveys a read-only, side-effect-free operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, usage context, return info plus note. Front-loaded, no redundancy, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a status tool with no parameters and an output schema, description covers purpose, usage, return structure, and a prerequisite. No gaps given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100% vacuously. Description adds no parameter info, but baseline for zero parameters is 4. No additional value needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with 'Get WireGuard VPN tunnel and peer status', a specific verb-resource pair. Lists concrete outcomes (health, handshake times, bytes, endpoints), distinguishing it from sibling status tools like opn_openvpn_status or opn_ipsec_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use this when you need to check WireGuard tunnel health...', providing clear context. Also notes plugin requirement. Lacks explicit when-not-to-use but differentiation from siblings is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that sensitive data is redacted by default, and describes the return structure. Without annotations, this provides necessary behavioral context, though could mention more about 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with action, no redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage alternatives, return type, and redaction. Could be more complete (e.g., prerequisites), but output schema exists to fill some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one boolean parameter; description explains redaction default behavior, adding meaning beyond the schema. Schema coverage is 0% but the narrative compensates sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it downloads config.xml backup as raw XML, distinguishes from siblings like opn_scan_config and opn_get_config_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (full backup) and when not (use opn_scan_config then opn_get_config_section for specific sections), naming alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It describes a non-destructive read operation and specifies return format (dict keyed by interface). Could mention potential empty results but adequate overall.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three lean sentences, front-loaded with verb and resource, no extraneous words. Each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and an output schema available, the description covers the essential behavior and return format fully. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. Description adds value by listing the statistics fields and return structure, exceeding the baseline of 4 for zero-param tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets per-interface traffic statistics, listing specific fields (bytes, packets, errors). It distinguishes from sibling tools like opn_dns_stats or opn_gateway_status by focusing on per-interface data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: for network utilization, interface errors, or traffic comparison. Lacks when-not or alternatives, but given the narrow scope, it's sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that changes take effect immediately, no savepoint protection, and that reconfigure starts the service. No annotations provided, so description carries full burden. Could mention potential service interruption but is sufficiently transparent for this type of tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise but includes necessary warnings and notes. Front-loaded with purpose, then usage context and important reminders. Slightly verbose due to multiple warnings but each is essential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all relevant aspects: purpose, usage context, prerequisite (plugin), required sequence (configtest), behavior (immediate, no savepoint), and output format. Zero-parameter tool with high completeness given no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters defined in schema. Baseline score of 4 applies. Description does not need to add parameter information, and it doesn't repeat anything from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'apply' and resource 'pending HAProxy load balancer configuration changes'. Distinguishes from siblings by indicating it is for applying changes after making HAProxy configuration modifications, and explicitly warns against calling haproxy/service/start.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use: after making HAProxy configuration changes. Includes important warnings: always call configtest before, do not call start after. Also notes lack of savepoint protection and requirement for os-haproxy plugin.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states that changes are applied immediately and describes the return dict with 'removed', 'not_found', 'dnsbl_status', and 'service_status'. It does not mention authentication or rate limits, but covers the essential behavioral aspects of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with no unnecessary words. It follows a logical structure: purpose, usage context, prerequisite, parameter list, and return value. The key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters), the description covers all necessary aspects: purpose, usage scenario, parameter details, and return format. The presence of an output schema doesn't reduce the need for completeness, and the description adequately covers the return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the uuid as 'blocklist UUID from opn_list_dnsbl' and the domains parameter as 'comma or newline-separated', adding meaningful detail beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove domains from a DNSBL allowlist', specifying the verb 'Remove' and the resource 'domains from a DNSBL allowlist'. This distinguishes it from siblings like opn_add_dnsbl_allowlist and opn_update_dnsbl.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'when you no longer need a domain allowlisted and want to re-enable DNSBL blocking for it.' It also provides a prerequisite by referencing opn_list_dnsbl to get the UUID. It does not explicitly mention when not to use it, but the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses return format and version-dependent nesting. It implies a read operation with no side effects, which is accurate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: purpose, usage guidance, return details. Front-loaded and no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema, the description adequately covers return format and version differences. Could mention error cases or rate limiting but it's not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description adds value by explaining the return structure, exceeding the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves OPNsense system status including firmware version and product info. This distinguishes it from sibling tools that perform mutations or other queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: to check firmware version, system name, or verify reachability. Does not mention when not to use, but given no direct sibling overlap, it's sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It describes the read-modify-write behavior, states that only provided parameters are changed, and notes that aliases are metadata definitions not affecting traffic until referenced. This provides good insight into the tool's behavior, though it could mention error handling 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear action statement, usage scenarios, behavioral note, prerequisite, parameter list with descriptions, and return format. No unnecessary words, highly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, 1 required) and the presence of an output schema, the description is complete. It covers purpose, when to use, prerequisites, parameter details, and return value. It also provides a behavioral note about savepoint protection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning to each parameter: uuid as alias UUID from list, name format, content separated by newlines, alias_type with enumerated values, and enabled as boolean. This far exceeds the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing firewall alias by UUID, specifying the exact actions (rename, change content, description, type) and differentiates from siblings like opn_add_alias, opn_delete_alias, and opn_toggle_alias.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use (rename, change content, etc.) and recommends using opn_list_firewall_aliases first. It also explains that savepoint protection is not needed. However, it does not explicitly contrast with alternative update tools for other resources (e.g., opn_update_firewall_rule), but it is clear within its own domain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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 states the tool lists leases and returns a dict with address, mac, hostname. It does not mention side effects, but since it's a read operation, it's inherently non-destructive. A perfect score would require explicit statement of read-only nature, but the description is still transparent enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: 5 sentences, each serving a clear purpose. It is well-structured with purpose first, then usage instruction, warning, recommendation, and return format. No redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has an output schema, the description does not need to fully detail return values, but it summarizes the key fields. The description covers purpose, usage conditions, and return format adequately for a simple list tool. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the description does not need to explain any. Schema coverage is 100% (empty schema). Baseline for 0 parameters is 4. The description adds value by specifying the output fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists DHCPv4 leases specifically from the ISC DHCP server, distinguishing it from sibling tools for other DHCP backends. It specifies the action (list), resource (DHCPv4 leases), and context (legacy ISC DHCP server).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use the tool (when OPNsense uses ISC DHCP plugin), warns that ISC DHCP is being phased out in favor of dnsmasq or Kea, and recommends checking the backend first with opn_scan_config. This provides clear guidance and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully compensates by stating it is a read operation (Get) and discloses return format with fields. No destructive or rate-limit information needed for this simple read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, first defines purpose, second lists use cases, third specifies output. Front-loaded, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 (implied by 'Returns:'), description is fully sufficient. Explains what tool does and when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (schema coverage 100% vacuously). Description adds no parameter info, which is appropriate. Baseline 4 for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'NDP table showing IPv6-to-MAC address mappings.' It distinguishes from sibling opn_arp_table by explicitly calling it the IPv6 equivalent of the ARP table, and lists specific use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: find MAC from IPv6, identify devices, troubleshoot reachability. Also implies IPv4 alternative via 'IPv6 equivalent of the ARP table', guiding away from this tool for IPv4 tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses dependency (os-ddclient plugin) and return format (dict with status). Does not mention potential side effects or permissions, but for a reconfiguration tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences plus a note, no unnecessary words. Purpose is front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and existence of output schema, the description covers purpose, usage guidelines, dependencies, and return value. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so schema coverage is 100%. Description adds context about when to use and prerequisites, going beyond the schema. Baseline 3 is appropriate, but the extra context raises the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool applies pending DDNS configuration changes, and distinguishes from opn_add_ddns_account which auto-reconfigures. The verb 'apply' and resource 'DDNS configuration changes' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (after manual edits, for troubleshooting) and when not needed (after opn_add_ddns_account). Provides clear context for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it restarts Unbound, changes take effect immediately, and cannot be auto-reverted. Also mentions return type. Could add detail on whether operation is blocking, but overall very informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with main action, then context, caution, and return type. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and simple tool, description fully covers purpose, usage context, behavioral notes, and return value. Output schema exists but not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline 4. Description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Apply pending Unbound DNS resolver configuration changes' and resource 'Unbound DNS resolver'. Distinguishes from sibling reconfigure tools for other services (ddclient, dnsmasq, haproxy).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use after making DNS configuration changes (adding overrides, forward zones) and warns about the lack of savepoint protection and immediate effect. Provides a clear when-to-use and caution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden. It transparently describes the audit scope (11 areas), output structure (findings with severity, recommendations, compliance references), and implies it is a read-only assessment. It provides sufficient 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear title sentence, bullet-like list, and usage guidance. It is concise, front-loading the main purpose, and every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a security audit covering multiple areas and the existence of an output schema, the description provides a complete picture of what the tool does and what the output contains (structured report with severity, recommendations, compliance). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters (coverage 100%), so baseline is 4. The description adds no parameter-specific meaning, which is appropriate since there are none. It correctly focuses on tool behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs a comprehensive security audit of OPNsense firewall, listing 11 specific security areas checked and mentioning compliance frameworks. It distinguishes itself from sibling tools (which perform individual management operations) by being a holistic audit tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'assess the security posture, identify misconfigurations, or perform a routine health check.' While it doesn't explicitly list when not to use or alternatives, the unique audit purpose makes usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behavioral traits: savepoint protection details for OPNsense < 26.7, auto-revert in 60 seconds unless confirmed, and the change in behavior on 26.7+. It also warns about the risk of lockout and guides the user to check opn_mcp_info. This adds significant context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and structured with clear paragraphs: first sentence is the core purpose, then usage, then savepoint specifics, then pre-conditions. It is a bit longer than needed but every sentence provides essential operational detail, so it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (version-dependent behavior, destructive risk, and single parameter), the description covers key aspects: prerequisites, safety measures, and return format. It lacks some details like error handling or exact response structure, but the output schema exists, so the description complements it well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage for the 'uuid' parameter, but the description explicitly states to find the UUID via opn_list_firewall_rules and that the uuid is returned in the output. This adds enough semantic context to compensate for the schema's lack of description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Toggle a firewall filter rule's enabled/disabled state' with a specific verb (toggle) and resource (firewall filter rule), and distinguishes it from sibling tools like opn_list_firewall_rules and opn_update_firewall_rule by focusing on the enable/disable flip.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'when you need to temporarily disable a rule for testing or re-enable a previously disabled rule' and offers clear alternatives: 'Use opn_list_firewall_rules first to find the UUID' and 'take a config backup with opn_download_config'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behaviors: only provided parameters are changed, ddclient is automatically reconfigured, changes take effect immediately, and return dict includes 'result', 'uuid', 'reconfigure_status'. This meets the full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Efficiently structured: purpose first, then usage context, effect, prerequisite step, parameter list, and return value. No wasted words; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, no enums, no nested objects) and presence of output schema, the description covers all necessary aspects: it explains when to use, how to prepare (list first), what happens after update, and what is returned. The sibling tools list is large but the description focuses on its own purpose without needing explicit comparisons.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description lists all 9 parameters with brief explanations (e.g., hostname: 'fully qualified domain name'). While it lacks detailed format or enum lists, it provides sufficient meaning beyond the schema for most parameters. Examples given for some values (e.g., 'cloudflare', 'web_dyndns') help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update', the resource 'Dynamic DNS account', and specifies 'by UUID'. It distinguishes from sibling tools like opn_add_ddns_account and opn_delete_ddns_account by the update action and applying configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 change...' and recommends using opn_list_ddns_accounts first to find the UUID. Does not explicitly state when not to use, but the sibling tools cover create/delete/list/reconfigure separately, making the guideline clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden of behavioral disclosure. It explains savepoint auto-revert on OPNsense < 26.7, immediate persistence on 26.7+, the 60-second confirmation window with opn_confirm_changes, and lockout risk mitigation. It also discloses the return value shape, which is not specified elsewhere.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense but well-structured, with a clear lead action, usage statement, behavioral warnings, parameter bullets, and return type. Despite its length, every sentence adds necessary context for safe invocation, especially given version-dependent behavior and no annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's mutation risk, version-specific savepoint behavior, and minimal schema with no annotations, the description covers purpose, when to use, safety precautions, parameter semantics, and return values. This is fully adequate for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must fully compensate. It explains that 'uuid' comes from opn_list_firewall_rules and that 'categories' is a comma-separated list of category UUIDs from opn_list_firewall_categories, including the empty-string behavior to clear categories. This provides source and formatting guidance beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and target: 'Assign categories to a firewall rule by UUID.' This clearly distinguishes it from sibling tools like opn_update_firewall_rule or opn_toggle_firewall_rule, which handle different aspects of rule management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'Use this when you need to categorize or re-categorize a firewall rule' and provides preconditions, including checking opn_mcp_info and taking a backup with opn_download_config when savepoint support is unavailable. It does not explicitly name alternative tools for cases where this tool is not appropriate, but the version-specific guidance makes usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it delivers extensively. It discloses savepoint auto-revert behavior, version-specific differences, the need to confirm changes on older OPNsense, the lack of automatic rollback on 26.7+, and recommends config backup when savepoint support is unavailable. This is rich, actionable behavioral context well beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but necessarily so for a 19-parameter, behaviorally complex tool. It is front-loaded with the core purpose, then usage guidance, then critical version caveats, then the parameter list, then return values. Every section earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 19 parameters, no annotations, zero schema-level parameter descriptions, and a mutation-heavy operation, this description is exceptionally complete. It covers invocation, prerequisites, operation scope, safety/rollback behavior, all parameter semantics, and return shape. The output schema exists, so the description appropriately does not need to elaborate return values beyond naming the keys.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does. Every one of the 19 parameters is listed with concise semantics and value hints (e.g., action: 'pass', 'block', or 'reject'; source_net: source address/network or 'any'; quick: first-match wins vs last-match-wins). This adds meaning the raw schema completely lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource statement: 'Update an existing MVC firewall rule by UUID with savepoint protection where supported.' It clearly distinguishes this from sibling tools like add/delete/toggle/list firewall rules by focusing on modifying existing rules by UUID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Use this when you need to modify a firewall rule's action, source/destination, protocol, ports, or other properties.' It also directs agents to call opn_list_firewall_rules first to find the UUID and check opn_mcp_info for savepoint support. It does not explicitly state when not to use it versus alternatives like opn_toggle_firewall_rule, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It discloses that it flushes DNS cache, does not use savepoint protection, changes are immediate and irreversible, and returns specific dict keys. All behavioral traits are transparently documented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs with a note. The first sentence states the core action, then usage examples, then caution. Every sentence adds value, no fluff. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 all necessary aspects: what it does, when to use, side effects, return structure. It is complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100% trivially. Per guidelines, baseline for 0 params is 4. The description does not need to add param info, and it doesn't miss anything.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reloads DNSBL blocklist files and restarts Unbound to apply them. This verb+resource pattern is specific and distinguishes it from sibling tools like opn_set_dnsbl (which probably configures rather than reloads) and opn_list_dnsbl (which lists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use: when DNSBL lists need refreshing without configuration change, e.g., after service restart or to force picking up pre-generated blocklists. It also warns about immediate effect and lack of auto-revert, which implies when not to use (if rollback needed). This provides clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are provided, the description fully discloses behavior: downloads full config, parses into sections, detects runtime state, caches results, and that subsequent calls return cached version unless force=True. It also lists the returned keys. This is comprehensive for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short paragraphs, each serving a clear purpose: purpose/initial use, caching behavior, and force usage with sibling recommendation. No redundant sentences. Front-loaded with the main verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (full config scan) and the presence of an output schema, the description still details what the return dict contains (firmware, plugins, dhcp, etc.) and notes caching behavior. It also mentions the sibling tool for deeper access. This is complete and leaves no ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter is 'force' (boolean with default false). The description adds meaning by explaining 'Call with force=True to rescan after manual config changes on the firewall.' This clarifies when and why to use it. Schema coverage is 0% but the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Scan the OPNsense configuration and build a cached inventory.' It specifies the action (scan/build), resource (configuration), and outcome (cached inventory). It also distinguishes itself from sibling tools by recommending opn_get_config_section for drilling into specific sections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to 'Use this FIRST when starting a new session.' Provides clear guidance on when to use force=True (after manual config changes) and directs to a sibling tool for further drilling: 'Use opn_get_config_section(section) to drill into specific sections.' This covers both when to use and when not to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: savepoint protection on OPNsense <26.7 with 60-second auto-revert, immediate changes on 26.7+, and the need to take a backup if savepoint_support is false. This adds crucial operational detail beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, usage, parameters, returns) and each sentence adds value. It is detailed yet not redundant, front-loading the core purpose and organizing the rest logically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no annotations, and the complexity of version-dependent behavior, the description covers all necessary aspects: parameter explanations, savepoint differences, workflow prerequisites, and return type. It is complete and actionable for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description lists every parameter with an explanation, example, or type (e.g., destination_port: '8080', '3000-3010'). This fully compensates for the lack of schema descriptions, giving agents the meaning and acceptable values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing NAT port forwarding rule by UUID, distinguishing it from add/delete/list operations. It specifies the verb, resource, and identifier method, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool (to change target IP, port, or properties), notes that only provided parameters are changed, and instructs to use opn_list_nat_rules first and check opn_mcp_info for savepoint support. This provides clear context and prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/lucamarien/opnsense-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server