opnsense-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation5/5
Each tool targets a distinct resource or action: aliases are split into config, live table, references, and updates; firewall diagnostics are split into log, states, statistics, and kill; rules are split into search, detail, statistics, toggle, and apply. Cross-references explicitly warn against using the wrong tool, so an agent should rarely select the wrong one.
Naming Consistency4/5
All tools use the opnsense_verb_noun pattern with snake_case, which is consistent. However, verbs vary for similar operations: search_aliases vs list_interfaces vs get_routes, and query_states vs search_dns_queries. The differences are mostly intentional (search for filtered, list for enumeration, get for single item), but the boundary is not perfectly uniform.
Tool Count4/5
26 tools is slightly above the typical well-scoped range, but the breadth of the OPNsense domain justifies the number. Each tool covers a distinct feature area (aliases, rules, states, DNS, VPN, interfaces, DHCP, system, services), so none feels redundant. The count is high but not excessive given the scope.
Completeness4/5
The tool surface covers most core firewall workflows: searching and modifying rules, inspecting aliases and live tables, querying states and logs, checking DNS and VPN status, and managing services. Gaps exist for creating/deleting rules and aliases, but these are intentionally left out for safety, and opnsense_api_request provides a raw fallback for any missing endpoint.
Average 4.8/5 across 26 of 26 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
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.json to 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

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral detail: it returns the exact JSON schema, mentions that sections are omitted if their endpoint is unavailable, and explains the kind of state covered. This goes beyond the annotations, though it doesn't disclose latency or auth specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, troubleshooting context, args, returns, and examples. It is front-loaded with the main purpose. Though somewhat verbose, each sentence earns its place, providing useful operational context and selection guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description is comprehensive. It covers the purpose, usage context, input parameter, return schema (including the JSON structure and omitted sections), and when not to use it. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions the single parameter (response_format) and its allowed values ('markdown' or 'json'), but adds little beyond what the input schema already provides. The schema's nested description offers richer guidance about format trade-offs, so the description's contribution is minimal. Still, it at least identifies the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get the state of the Unbound DNS resolver: whether it is running, whether DNS blocklisting is active, and its cache and query counters.' It clearly distinguishes itself from sibling tools by explicitly stating not to use it for individual lookups, pointing to opnsense_search_dns_queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use context: 'Clients reporting "the internet is down" when routing is fine is almost always DNS. Check here before looking at firewall rules.' Also gives concrete examples: 'Use when: Is DNS working? / Don't use when: You want to see individual lookups (use opnsense_search_dns_queries).'
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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false. The description adds useful behavioral context beyond the annotations: states represent live connections with byte/packet counters, an empty filter returns a potentially very large result, and the tool is safe for introspection. It does not disclose pagination behavior or rate limits, but these are partially covered by offset/limit parameters and the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a short intro, a labeled Args section, a Returns block with a full JSON schema, and concise usage examples. It is information-dense but not bloated; each section earns its place, though the JSON schema duplication could be trimmed if an output schema were linked elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity, the description is fully self-contained: it explains the tool's purpose, parameter meaning with defaults, the output format (both markdown and JSON with a schema), and provides concrete usage examples. The presence of an output schema in the description plus the distinction from the log tool makes the tool's behavior and return contract clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all nested parameters (filter, rule_id, limit, offset, response_format), including defaults and constraints. The description's Args block essentially repeats this information, adding little semantic value beyond a few usage hints (e.g., filter matches address or port). Since schema coverage is effectively complete, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Query the pf state table to see connections currently tracked by the firewall.' It clearly distinguishes from history (logs) and other lifecycle tools by framing states as current activity. The example also reinforces this by explicitly contrasting with opnsense_get_firewall_log.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete 'Use when' scenarios with example filters (e.g., checking if a host is communicating, finding what saturates the WAN) and a clear 'Don't use when' exclusion that names the alternative (opnsense_get_firewall_log for history). This gives an agent strong guidance on when to select this tool over 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?
The annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it explains that the tool reads the live pf table reflecting resolved hostnames, downloaded feeds, and refreshed GeoIP sets, and it documents the specific 'not-loaded' error case when no enabled rule references the alias. This depth of behavioral disclosure is excellent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear lead sentence, followed by structured Args, Returns, and Error Handling sections. It is appropriately sized for the tool's complexity, with every part serving a purpose and no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers what the tool does, when to use it, parameter semantics, return format (including an inline JSON schema), and error handling. It leaves no significant gap for an AI agent to determine correct invocation and interpretation of results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides comprehensive descriptions for all parameters, including defaults, ranges, and format guidance. The description's Args section repeats this information without adding substantial new meaning, so a baseline score of 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get the addresses currently loaded in an alias's pf table.' This clearly states the tool's function and differentiates it from sibling tools like opnsense_search_aliases (searching alias configuration) and opnsense_update_alias_entries (modifying aliases). The live-table qualification further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a concrete use case: when a rule using an alias misbehaves, comparing live table contents to alias configuration helps detect failed feed refreshes. This gives clear context for when to use the tool, though it does not explicitly name alternative tools or exclusion 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?
Annotations already cover the safe read-only nature. The description adds the output contract (markdown vs JSON, pagination with has_more/next_offset) and the search behavior, which is valuable context beyond the annotations. It does not mention error conditions, but given the read-only hint, the transparency 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, usage context, args, returns, and examples. Every part earns its place, and the examples are concise and illustrative. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only query tool, the description covers the what, when, parameters, output format, and pagination behavior. The annotated safety hints and the output schema in the description make this a fully self-sufficient documentation for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema has descriptions for each field, the context signals indicate 0% coverage at the top level, so the description's Args section compensates by restating all parameters with defaults and meanings. The examples also show how to map natural-language queries to search values, adding practical semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the firewall's active routing table, including default, policy, and VPN routes. This verb+resource combination is specific and distinct from all sibling tools, none of which deal with routing tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides two concrete diagnostic scenarios: 'traffic reaches the firewall but leaves the wrong way' and 'checking that a VPN tunnel installed the routes it should have'. It gives clear context for when to use the tool, though it does not explicitly 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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds valuable behavioral context beyond annotations, notably that 'Sections whose endpoint is unavailable on this release are omitted' and the detailed return schema with optional (temperature, disk) sections. This is useful for setting expectations about output variability, which annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and efficiently organized: one-sentence purpose, a 'Start here' usage note, an explicit exclusion, a compact Args list, a structured Returns block, and practical Examples. Every sentence earns its place, and there is no fluff or repetition. The length is justified by the amount of useful information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only status tool with a rich output schema, the description covers every relevant aspect: what the tool does, when to use it, when not to use it (with alternatives), parameter defaults, the return format, and the edge case of omitted sections on unsupported releases. The agent has everything it needs to select and invoke this tool correctly in the appropriate context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides comprehensive descriptions for all three parameters (defaults, types, and even guidance on when to choose 'json' vs 'markdown'). The description's Args section repeats this information but adds no new semantics beyond what the schema offers. Since the schema coverage is effectively high from the schema's own descriptions, a baseline of 3 is appropriate; the description does not meaningfully enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Get a health overview of the OPNsense firewall' and enumerates exactly what is covered: version, uptime, load, memory, optional temperature sensors, and optional disk usage. This specific verb+resource framing clearly distinguishes it from sibling tools like opnsense_get_firmware_status and opnsense_get_interface_statistics, which are explicitly named as alternatives for other concerns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('Start here when asked how the firewall is doing, what version it runs, or whether it is under load') and explicit when-not-to-use with named alternatives ('This does NOT report firmware updates - use opnsense_get_firmware_status for that' and 'Don't use when: You want per-interface throughput (use opnsense_get_interface_statistics)'). This is exactly the kind of actionable usage guidance that helps an agent select the right 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?
Beyond the readOnlyHint annotation, the description discloses a critical behavioral caveat: without Unbound's reporting enabled, the tool returns an empty result even on a busy network. It also details the return schema and that 'blocked_only' filters for blocked queries, adding context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, prerequisite, usage pairing, args, return schema, and examples. Every sentence adds value, and the length is justified by the tool's complexity and nested parameters. It is front-loaded with the purpose and critical prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with nested parameters and a rich return schema, the description is complete: it covers prerequisites, parameters, output structure, and examples. The explicit return schema compensates for the absence of a structured output schema in the definition, making the tool fully self-documenting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists all parameters with types and defaults, and adds practical examples for 'search' and 'blocked_only' that illustrate their intended use. While the nested schema already contains descriptions, the description's examples provide actionable semantics beyond the schema, especially given the top-level 'params' object itself lacks a description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search recent DNS lookups seen by the Unbound resolver, including which client asked and whether the answer was blocked.' This immediately distinguishes the tool from siblings like opnsense_get_dns_overview by focusing on query-level search rather than an overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases ('Use when: What did this device look up?', 'Is anything hitting the blocklist?') and a prerequisite (Unbound reporting must be enabled). It also suggests pairing with firewall logs for behavioral investigation. However, it does not explicitly mention when to prefer an alternative sibling tool.
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 discloses important behavioral traits beyond the annotations: OPNsense caches update checks, potentially causing stale results, and that the firmware/check endpoint can force a refresh. It also reiterates safety by stating 'This tool never installs anything.' The readOnlyHint/idempotentHint are already present, but the cache caveat adds meaningful 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, followed by a focused caveat about caching, then Args, Returns, and Examples sections. Every sentence earns its place without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter, annotations cover safety, and the description includes a detailed return schema and usage examples. It fully equips an agent to select and invoke the tool correctly, including handling stale results and choosing the output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (response_format) is mentioned in the Args section but only lists the two options ('markdown' or 'json') without explaining their trade-offs. The input schema's property description actually provides more useful guidance ('json returns every field... better when chaining values'). Since schema coverage is low, the description should have compensated but did not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Check for pending OPNsense updates and report the installed version and repository state.' It also explicitly distinguishes from a sibling tool by noting 'Don't use when: You want uptime or load (use opnsense_get_system_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Don't use when' examples, names an alternative tool (opnsense_get_system_status), and explains when to use opnsense_api_request to force a refresh when results are stale. Also clarifies that the tool never installs anything.
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 discloses critical behavioral traits beyond the read-only annotation: the evaluation order semantics ('last match wins', 'sequence' column), the scope limitation to the MVC filter model (legacy rules may be missing), and the difference between markdown and JSON response formats. This adds substantial context for safe and correct use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (purpose, evaluation order, scope, args, returns, examples) and is front-loaded with the most important information. The Args section duplicates schema content, making it slightly longer than necessary, but everything else earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is thorough: it explains the return schema, pagination fields, interpretation guidance ('read the matching rules in sequence order'), scope limitations, and gives multiple concrete usage examples. For a search tool with an output schema and rich annotations, this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for all parameters, so the description's Args section is largely redundant and even less informative (e.g., search is only described as 'Free-text filter' while the schema explains matching behavior). The natural-language examples add some usage nuance, but not enough to exceed the high schema coverage baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Search firewall filter rules' and includes the key distinguishing detail of returning rules 'in evaluation order' with specific fields. This clearly differentiates it from sibling tools like firewall logs, aliases, or NAT rule APIs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Don't use when' examples are provided, including the exact alternative for NAT rules (opnsense_api_request). This gives clear direction on when to select this tool over 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?
Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description goes far beyond by disclosing the savepoint mechanism, the 60-second automatic rollback, the requirement for OPNSENSE_ALLOW_WRITE=true, and the exact sequence including safe/unsafe skips. It also explains error handling for missing permissions or missing revision.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized with numbered sequence and clear sections (Args, Returns, Error Handling). It is somewhat repetitive between the sequence and the Args list, but given the complexity of the workflow, the length is justified and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the entire life cycle: prerequisites, savepoint, apply, rollback, cancel, and revert. It includes return format details (string or JSON) and error handling for two common failure cases. This is complete given the tool's complexity and the existing schema/annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions for mode, revision, and response_format are already informative, but the description adds critical workflow context: revision comes from mode='savepoint', how it is used in apply/cancel_rollback, and when it is required. This compensates for the 0% schema coverage signal at the top level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Activate staged firewall changes') and clearly identifies the resource ('staged firewall changes'). It also mentions automatic rollback protection, which distinguishes it from related sibling tools like opnsense_toggle_firewall_rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a detailed step-by-step workflow and explicitly references opnsense_toggle_firewall_rule as the mechanism for making changes before applying. It also warns about skipping steps. However, it does not explicitly state 'use this instead of X' or give a clear when-not-to-use scenario beyond the workflow itself.
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 beyond annotations: the write-permission requirement, specific disruptive effects (DNS breakage, VPN tunnel drops), and error handling (write-disabled explanation, 403 privilege message). This significantly exceeds what annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, warnings, args, returns, and errors. Each sentence provides necessary operational detail without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (write operation, multiple parameters, side effects), the description covers all essential aspects: permissions, consequences, parameter guidance, return values, and error cases. This is complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists all nested parameters with examples and clarifications (service_id for multi-instance, response_format options). It adds meaning beyond the schema by explaining behavior, such as 'default: ""' and the impact of response_format on chaining values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Start, stop or restart a service on the firewall.' This is a specific verb+resource and distinguishes from siblings like opnsense_list_services (read-only). The tool's purpose is 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: requires OPNSENSE_ALLOW_WRITE=true, warns about disruptive effects, and instructs to confirm intent before action='stop'. Also references opnsense_list_services for service id (implicitly via schema). However, it doesn't explicitly state 'when not to use' 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?
The annotations already mark this as read-only, non-destructive, and idempotent. The description adds valuable behavioral context by disclosing the API-first approach, the fallback to rule scanning when the API is unavailable, and that the output includes a 'source' field indicating which method was used. It also clearly states the fallback's coverage gap (filter rules only), which is important for the agent to assess reliability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose sentence, followed by a fallback explanation, Args, Returns, and Examples. It is front-loaded with the main use case and does not waste words. The extra length is justified by the need to explain the fallback logic and limitations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested input, API fallback, coverage limitations, and JSON output schema), the description covers all important aspects: what it does, when to use it, what the fallback means, input parameters, and return format. The output schema is described in enough detail for an agent to interpret results, and the annotations cover safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a nested object with 'name' and 'response_format', but the top-level 'params' field lacks a description, so schema coverage is effectively 0%. The description compensates by listing both parameters, defining the response_format values, and explaining that 'json' is better for chaining values into another call, which adds practical guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Find') and resource ('where an alias is referenced'), with a clear purpose ('so you know what would break if it changed'). It distinguishes from sibling tools like opnsense_get_alias_contents by focusing on references rather than the alias's own contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' examples for deletion and emptying scenarios. It also explains the fallback behavior and its limitations (filter rules only, not NAT or nested aliases), which implicitly tells the agent when not to rely on the result. However, it does not explicitly name alternative tools to use in those 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about covering core and plugin services, pagination fields, and the response format, without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args, Returns, and Examples sections. Each sentence contributes necessary information, and the content is front-loaded with the core purpose. It is detailed but not verbose, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with an output schema, the description explains pagination fields (total, has_more, next_offset) and provides concrete query examples. It also clarifies the distinction between markdown and JSON output, making it complete for the intended use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section mirrors the schema's parameter descriptions, but adds practical guidance, especially for response_format: 'json returns every field the API provided and is better when chaining values into another call.' The examples map intents to parameter values, which adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List services registered with OPNsense and whether each one is running,' which clearly states the action and resource. It distinguishes from sibling tools by explicitly directing the user to opnsense_control_service for restart operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use this to get the exact service id before calling opnsense_control_service' and includes examples with 'Use when' and 'Don't use when', naming the alternative tool opnsense_control_service. This fully satisfies the when/when-not/alternatives criteria.
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 discloses critical behavioral details beyond the annotations: the change is staged and not live, it requires a specific environment variable, and it may impact the user's own access path. The error handling is also described. These enrich the annotation hints (destructive, write, idempotent) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into concise sections: action, usage notes, args, returns, and error handling. Every sentence carries useful information, and the key behavioral caveats are front-loaded. It is detailed without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations and output schema, the description fully covers prerequisites, staging, return format, and error cases. It also provides operational advice (savepoint) that is essential for safe usage. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section lists uuid, enabled, and response_format with brief descriptions, but the input schema already provides detailed descriptions for these parameters, including the response_format distinction between compact markdown and full JSON. The description adds minimal extra meaning beyond restating the schema, so it is adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Enable or disable a single firewall rule,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like search_firewall_rules, get_firewall_rule, and apply_firewall_changes. It immediately conveys the exact action and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the prerequisite (OPNSENSE_ALLOW_WRITE=true), explains that changes are staged and require opnsense_apply_firewall_changes to take effect, and advises taking a savepoint before toggling rules that could affect the user's own access. This provides clear when-to-use and safety guidance, going well beyond a simple action statement.
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 discloses a critical behavioral nuance: counters reset on every ruleset reload, making a zero count mean 'not matched since last apply' rather than 'never matched.' It also advises confirming ruleset stability before drawing conclusions—valuable context well beyond the readOnly/idempotent 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (overview, caveat, Args, Returns, Examples). It is front-loaded with the most important information and every sentence contributes value, including the illustrative examples that make usage immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description is exceptionally complete: it covers purpose, parameter semantics, behavioral caveats, output schema, and concrete use cases. The existing output schema and annotations complement rather than replace this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the schema coverage signal showing 0%, the description fully documents every parameter (search, unused_only, limit, offset, response_format) and adds meaning beyond the schema by explaining the purpose of each and how to use them together. The included response schema further clarifies what each parameter influences.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific, action-oriented summary: 'Get per-rule pf counters' and enumerates the exact metrics (evaluations, packets, bytes, states). This clearly differentiates it from related tools like opnsense_get_pf_statistics by emphasizing the per-rule granularity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete 'Use when' examples tied to specific parameters (e.g., finding unused rules with unused_only=True, checking traffic on a specific rule with search). It gives clear context but does not explicitly name alternative tools or state when not to use this tool, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the readOnlyHint/idempotentHint annotations: it explains that WireGuard is connectionless, that there is no 'down' state to observe, and that a configured peer with no recent handshake is not connected regardless of interface status. It also discloses that a response key is omitted when a VPN type is not configured or its endpoint is absent, which is helpful for interpreting results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient and well-structured: a one-sentence summary, a focused paragraph on WireGuard interpretation, a compact Args block, a clear Returns schema, and two concrete examples. Every section serves a purpose and none is redundant filler; the WireGuard nuance is essential for correct use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers what the tool does, when to use it, how to parameterize it, what the return value looks like (including an output schema), and important interpretation caveats. Given the tool's moderate complexity, the available schema, and rich annotations, the description leaves no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though the schema already defines 'kind' and 'response_format', the description adds meaning beyond the schema by explaining the meaning of 'last handshake', advising that 'json' is better when chaining values into another call, and showing how the 'kind' parameter maps to concrete user questions. The Args section makes parameter choices and defaults explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Get the status of WireGuard peers and OpenVPN sessions, including last handshake times and transfer counters,' which clearly identifies the verb, resource, and scope. It distinguishes this tool from the many other opnsense_* siblings by focusing specifically on VPN tunnel status, reinforced by the title 'VPN Tunnel 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear 'Use when' examples ('Is my phone connected over WireGuard?' -> kind='wireguard', 'Who is on the VPN right now?' -> kind='both'), establishing appropriate contexts. It does not explicitly state when not to use this tool or name alternative tools, but the examples and resource specificity make the usage scenario 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?
Annotations already indicate read-only and idempotent, but the description adds meaningful context: enum fields are flattened from OPNsense's internal format to the selected value, and a not-found message is returned for invalid UUIDs. These behaviors go beyond the annotation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet structured with clear sections (Args, Returns, Error Handling). It front-loads the core purpose and every sentence supports decision-making without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers input, output format, and error handling thoroughly. For a single-parameter tool with an output schema, the description is complete and even explains return value details like markdown vs JSON and field flattening.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description's Args section explains both parameters: uuid source and response_format trade-offs. The schema already provides descriptions, but the tool description adds context like 'Rule UUID from opnsense_search_firewall_rules' and that json 'returns every field the API provided'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states clearly 'Get every configured field of a single firewall rule by UUID', which is specific verb+resource+scope. It also differentiates from the sibling search tool by noting 'The search tool returns a summary; this returns the full record'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool: 'which is what you need before changing or reproducing a rule'. It contrasts with the search tool and provides guidance on response_format selection: 'json is better when chaining values into another call'.
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?
Despite readOnly/annotations already declaring safety, the description adds crucial context: counters are cumulative since boot, throughput requires two calls, and rising errors imply duplex mismatch or bad cable. It also explains return format details, going well beyond 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Args, Returns, Examples), front-loaded with the core purpose, and every sentence is informative without unnecessary padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's modest complexity and the presence of an output schema, the description fully covers purpose, usage, parameter semantics, and return format. It even includes practical troubleshooting guidance, making it 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides examples and clarifies the device parameter (e.g., 'igb0' vs config name) and the response_format choice, adding value to the schema's already detailed descriptions. However, it mostly repeats schema information rather than introducing entirely new syntax or edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get packet, byte, error and collision counters per interface.' It clearly distinguishes this from live per-connection traffic by explicitly naming an alternative tool in the examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases: 'Use when: "Is the WAN dropping packets?" -> device="pppoe0"' and 'Don't use when: You want live per-connection traffic (use opnsense_query_firewall_states)'. This directly addresses when to use vs. 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?
Beyond the readOnly/idempotent annotations, the description adds valuable behavioral context: it explains the diagnostic significance of non-zero counters, notes that load-related drops are absent from firewall logs, and warns that returned keys vary by OPNsense release. This prepares agents for interpreting results and managing variability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into purpose, usage context, parameter listing, and return format. It is roughly 150 words but front-loaded with the core function, and every section earns its place without filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—nested parameters, multiple output formats, and release-dependent keys—the description covers purpose, parameters, return behavior, and a clear diagnostic use case. It is sufficiently complete for an agent to select and invoke the tool correctly without needing to enumerate every possible counter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description enumerates both parameters (section and response_format) with valid values and adds practical guidance, e.g., 'json' is better for chaining values. Though the input schema includes some descriptions, the tool description reinforces them and provides selection advice, compensating for the reported low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get packet filter engine statistics' and lists specific elements (state table usage, memory limits, counters, timeouts). This specific verb+resource combination distinguishes it from sibling tools like opnsense_get_rule_statistics or opnsense_get_firewall_log, which focus on per-rule or 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs to use this tool 'when the firewall drops traffic under load rather than by policy,' explaining why (state table exhaustion and memory limits produce non-zero counters without firewall log entries). This provides both a clear when-to-use and a distinguishing condition against rule-based drops, though it does not name a specific alternative tool.
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 goes well beyond the annotations (destructiveHint=true) by disclosing that it 'takes effect immediately and cannot be undone,' that it tears down every matching connection, that it does not change policy so clients may reconnect, and that OPNSENSE_ALLOW_WRITE is required. It also reveals rejection of wildcard filters, adding critical safety context not present in structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than minimal, but every section earns its place: core action, requirements, side effects, use cases, exclusions, args, return, and error handling. It is well-structured with a clear flow, though slightly verbose in the danger warnings which could be condensed without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent tool with a single parameter, the description is remarkably complete. It covers prerequisites, immediate effects, reversibility (or lack thereof), policy interactions, legitimate use cases, alternative tool usage, rejected inputs, return format, and error handling. The output schema further clarifies return values, but the description already does so thoroughly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the 0% schema coverage signal, the description provides detailed parameter semantics: 'filter (str): Address or subnet whose states to drop (required)' and 'response_format (ResponseFormat): 'markdown' or 'json'' with an explanation of when each format is preferable. It even includes example IP/subnet values in the schema but the description enriches the meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Drop tracked connection states matching an address or subnet.' This precisely distinguishes the tool from read-only siblings like opnsense_query_firewall_states and from opnsense_update_alias_entries, which is explicitly mentioned as the alternative for blocking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use: 'Legitimate uses are forcing a host back through a changed rule set, and cutting an active session from a compromised device.' It also explicitly says when not to use it: 'It is not a way to block a host; add the address to a blocked alias with opnsense_update_alias_entries for that,' and warns against flushing the entire state table.
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?
Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds meaningful behavioral context: it covers both Kea and ISC backends, states that auto-fallback behavior, warns that static IPs will not appear, and documents pagination via offset. It also clarifies output format differences. This fully transparent, non-contradictory disclosure is exemplary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into a lead sentence, a explanatory paragraph, and clearly labeled Args, Returns, and Examples sections. Every sentence earns its place: no filler, and the most important information is front-loaded. It is concise despite covering many aspects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description is thoroughly complete: it explains the primary use case, covers all parameters, notes limitations (statics excluded), describes the return format, and gives actionable examples. The output schema already details the return structure, and the description does not need to repeat it in depth, yet still provides a useful summary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides rich descriptions for each parameter (search, backend, limit, offset, response_format). The description's Args section largely repeats this, but the usage examples add meaningful extra semantics, such as partial IP search ("192.168.30.") and the distinction between markdown and JSON outputs for chaining. Thus it adds some value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "List DHCP leases handed out by the firewall, across the Kea and legacy ISC backends." It clearly states what the tool does and even distinguishes itself from the sibling opnsense_search_neighbors by noting that static IPs are not included, pointing to that alternative instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: "which is usually the best way to put a name to a device seen in firewall logs" and concrete examples (e.g., searching an IP or subnet). It also provides an exclusion: "Don't use when: The host is statically addressed (use opnsense_search_neighbors instead)." This makes the appropriate context unmistakable.
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 goes well beyond the annotations by disclosing immediate effect without a savepoint, the risk of cutting off traffic, per-entry partial failure reporting, and error handling behavior. It also warns about the lack of rollback, which is critical for a destructive tool. Annotations show destructiveHint=true, and the description provides the concrete risks and implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (main description, Args, Returns, Error Handling). It is detailed but every sentence adds value, from the immediate-effect warning to the explicit return schema. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive potential, the description fully covers when to use it, prerequisites, risks, return format (including JSON schema), and error handling. It also explains the one-at-a-time application and partial failure visibility, leaving no significant gaps for an AI agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists each parameter and its high-level meaning (name, action, entries, response_format), including constraints like 1-100 entries and add/delete actions, which partially overlaps with the schema's own descriptions. Since the schema coverage signal is 0%, the description compensates by clarifying the purpose and role of each parameter, though it doesn't detail patterns or examples beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Add or remove entries in an alias table.' It clearly distinguishes from sibling tools (search, get, find, etc.) and explicitly contrasts with rule edits, making it unambiguous that this is the mutation tool for alias entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use and when-not-to-use guidance: 'the right tool for blocking an address quickly, and the wrong tool for anything you have not verified.' It also states a prerequisite (OPNSENSE_ALLOW_WRITE=true) and contrasts with rule edits, which require an apply step.
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?
Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses raw JSON return, truncation at 20000 characters, camelCase naming conversion, refusal of specific dangerous endpoints, and error-handling behavior. This adds valuable behavioral context that annotations alone do not provide, and there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place: purpose, when-to-use, naming, permissions, args, returns, examples, and error handling are clearly separated and front-loaded with the core advisory. It is structured for quick scanning and contains no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's generic nature and high complexity, the description covers all necessary aspects: scope, endpoint naming, write permissions, forbidden operations, return format/truncation, and error handling. The output schema exists, so the description does not need to enumerate fields, and it still provides complete guidance for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section explains each sub-parameter with types, defaults, and concrete examples (e.g., 'List NAT port forwards' -> module='firewall', command='searchRule'). This goes beyond the input schema and compensates for the lack of top-level parameter description, showing how to map user intent to valid parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Call any OPNsense API endpoint directly' and distinguishes itself from siblings with 'Use this only for endpoints the other tools do not cover.' It lists concrete examples (NAT rules, traffic shaping, IDS/Suricata) and names the sibling tool style ('dedicated tools'), making the tool's unique scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance: 'Reach for it when you need something outside their scope' and 'Don't use when: A dedicated tool exists; it will give better-structured output.' Also explains the permission conditions for writes (OPNSENSE_ALLOW_WRITE, confirm) and forbidden endpoints, which helps the agent decide whether this tool is appropriate.
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 discloses two non-obvious behavioral caveats: only rules with logging enabled produce entries, and filtering is local to the retrieved window. It explains that absence of a log entry is not evidence of blocking, adding significant context beyond the readOnlyHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but exceptionally well-structured: intro, caveats, args, return schema, and examples. Every sentence is informative, and the front-loaded caveats prevent misinterpretation. No redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a complete picture: purpose, usage scenarios, caveats, full parameter semantics, return schema in both markdown and JSON, and pagination fields (has_more, next_offset). It also names a sibling tool for alternative use, making it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 0%, the description enumerates every parameter with meaning, defaults, and examples. It clarifies that 'address' is a substring match, 'port' is exact, and interface uses device names (with a reference to opnsense_list_interfaces). This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Read recent firewall log entries') and resource, and explicitly frames the tool as the primary for 'why was this traffic blocked'. This clearly distinguishes it from sibling tools like opnsense_query_firewall_states and opnsense_get_pf_statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete 'Use when' examples (e.g., 'Why can't the IOT camera reach the internet?') and an explicit 'Don't use when' with an alternative tool (opnsense_query_firewall_states). It also gives guidance on handling log absence and filter windows.
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 annotations already indicating read-only, idempotent behavior, the description adds meaningful context: it explains the mapping between config names and device names, notes that include_disabled defaults to True (so down interfaces are returned by default), and clarifies the two output formats (markdown vs JSON). This goes beyond the structured 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but meticulously structured: overview, mapping role, Args list, Returns schema, and Examples. It is front-loaded with the core purpose, and each section earns its place by clarifying invocation and output expectations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (pagination, filtering, output formats), the description is complete. It includes a full output schema, clear parameter documentation, and usage boundaries. The output schema covers return values, so the description need not restate them, and the examples cover common queries.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the schema having descriptions for nested fields, the top-level 'params' parameter lacks a description (0% coverage signal). The description compensates with an 'Args' section that explains each field, provides defaults, and gives search examples ('vlan', 'GUEST'). This adds practical meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'List the firewall's interfaces with their config name, device name, addresses and link status.' This precisely states what the tool returns, and the following mapping explanation distinguishes it from other interface-related tools like opnsense_get_interface_statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Call this first whenever a question spans both worlds' and concrete examples show when to use (e.g., 'which rules apply to the IOT VLAN') and when not to use (throughput counters → use opnsense_get_interface_statistics). This directly addresses alternative tool 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?
Beyond the readOnlyHint and idempotentHint annotations, the description reveals the crucial nuance that URL table/GeoIP aliases return configured feed URLs or country lists, not currently loaded addresses. It also documents response pagination (total, count, has_more, next_offset) and response formats, adding significant 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While relatively long, the description is tightly organized into Args, Returns, and Examples sections, with every sentence adding value. The main purpose is front-loaded, and the detailed sections are warranted given the complexity and the important distinction from sibling tools.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the output schema, pagination behavior, parameter semantics, usage examples, and the critical differentiation from related tools. It leaves no major gaps for an agent to correctly select and invoke the tool, making it complete in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by enumerating all parameters (search, alias_type, limit, offset, response_format) with their meanings and defaults. It also clarifies the difference between markdown and json output formats, giving practical guidance beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search configured firewall aliases and their types, contents and descriptions' – a specific verb and resource that clearly defines the tool's scope. It further distinguishes itself from the sibling opnsense_get_alias_contents by clarifying the difference between configuration and live pf contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit examples for when to use the tool ('What aliases exist?', 'Show me the GeoIP aliases') and an explicit 'Don't use when' clause pointing to opnsense_get_alias_contents for live addresses. This directly addresses usage boundaries 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?
Even with annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description adds important behavioral context: entries only exist for devices that communicated recently, absent entry does not prove offline, and resolve_hostnames adds latency. This goes beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with an intro, usage notes, Args, Returns, and Examples sections. Each sentence adds value: the limitations, parameter semantics, return schema, and usage examples are all relevant and non-redundant. It is concise despite covering many aspects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool description covers purpose, usage scenarios, limitations, parameter details, return format, and concrete examples. It is complete for a search tool with output schema and annotations. The provided context signals (schema coverage, output schema) are all addressed or supplemented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an Args block that explains every parameter (search, family, resolve_hostnames, limit, offset, response_format) with defaults and practical examples (e.g., search='a4:83:e7'). This enriches the schema, which already provides good descriptions, making parameter usage fully clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Search the ARP (IPv4) and NDP (IPv6) neighbour tables to find which device holds an address, or which addresses a MAC has.' This clearly distinguishes from sibling tools like opnsense_list_dhcp_leases, and later examples reinforce the exact 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('fastest way to identify an unknown host on a segment'), when not to use ('Don't use when: You want the full DHCP allocation'), and suggests pairing with opnsense_list_dhcp_leases for a fuller picture. Provides clear alternatives and exclusions.
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:

[![opnsense-mcp MCP server](https://glama.ai/mcp/servers/aesaganda/opnsense-mcp/badges/card.svg)](https://glama.ai/mcp/servers/aesaganda/opnsense-mcp)

Score Badge

Copy to your README.md:

[![opnsense-mcp MCP server](https://glama.ai/mcp/servers/aesaganda/opnsense-mcp/badges/score.svg)](https://glama.ai/mcp/servers/aesaganda/opnsense-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/aesaganda/opnsense-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server