rule_hit_and_shadow_analysis

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

No annotations are provided, so the description carries the full burden. It discloses the read-only nature with the '[READ]' prefix, explains the analysis semantics (top-down, pf-exact evaluation), and states every finding names the offending/covering rule uuid. It could add more on edge cases or error behavior, but the disclosure is solid for a read-only analysis tool.

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

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

The description is well-structured with a brief summary line, a clarification paragraph, and an Args section. It's front-loaded with the most important purpose first. Slightly verbose in the analysis paragraph but every sentence contributes meaningful details about the evaluation semantics.

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

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

Given no output schema, the description helpfully documents the return dict shape ({rulesEvaluated, unusedCount, shadowedCount, redundantCount, unusedRules, shadowedRules, redundantRules, note}). With 3 optional parameters and no annotations, it covers the invocation modes, semantics, and return format well. Minor gaps: no mention of what happens with conflicting inputs or empty rule lists, but the overall completeness is strong.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It does: 'rules' is described as injected rows with an explicit field list, 'interface' as an optional filter when pulling live, and 'target' as the firewall name with omit-for-default behavior. This adds meaningful semantic context beyond the bare schema.

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

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

The description has a specific verb + resource ('Flag never-hit enabled rules and shadowed/redundant rules') and clearly explains what the tool detects: dead/misordered rules, shadowed rules, and redundant rules. It distinguishes well from sibling tools by describing the specific rule-analysis behavior versus status/list tools, and explains the top-down evaluation semantics.

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

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

The description explicitly states the operational context: rules are compared 'in list order, top-down, exactly as pf evaluates them,' and gives clear guidance that one can pass 'rules' for pure analysis or 'a target to pull live.' It explains the optional interface filter and default target behavior. This provides strong when-to-use and how-to-invoke guidance.

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