kill_states

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

With no annotations provided, the description carries the full burden, and it delivers richly. The [WRITE][risk=medium] tag signals mutation and risk level. It clearly documents the side effect (drops tracked connections), the self-inflicted consequence (own connection state flushed causing apparent failure), and reassures that access is not lost. This is a model of behavioral disclosure for a destructive operation.

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

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

Front-loaded with a clear [WRITE][risk=medium] tag and one-line purpose. The warning paragraph is tight and fills a critical gap. Args are listed compactly with useful semantics. Every sentence earns its place with no filler.

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

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

For a destructive, self-impacting operation with 0% schema coverage, no annotations, and no output schema, the description covers the purpose, the danger, the error-signature behavior, the access-safety reassurance, and all parameters. The dry_run escape hatch is mentioned. There is little an agent could be left unsure about for selecting and invoking this tool.

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

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

Despite 0% schema description coverage, the description explains all three parameters: filter_ip (optional source IP scope, blank = all states), dry_run (preview without flushing), and target (firewall target from config, omit for default). This fully compensates for the empty schema coverage, adding type/format and default semantics for each.

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?

Clear verb+resource: 'Flush pf state-table entries.' The tool distinctly operates on firewall state table entries, which is clearly differentiated from siblings like states_table (which presumably lists states), rule_states, and toggle_rule. The optional filter_ip scoping is also stated upfront.

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

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

Explicitly warns about when NOT to use it: dropping tracked connections means this tool's own connection state is flushed, so the call may appear to fail — a lost response, not a lockout, and a blind retry is the wrong reaction. It positions dry_run=True for preview and notes the permitting rule is untouched. This is exceptional guidance that addresses the risk scenario directly.

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