opnsense_query_firewall_states

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.

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.

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.

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.

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.

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.