firewall_log

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

The description clearly discloses the envelope return format, defines each field (entries, returned, limit, truncated), and critically explains the 'truncated' flag behavior — telling the agent to re-run with a higher limit rather than trusting the result as complete. This is valuable behavioral context beyond what any annotation would provide, since no annotations exist.

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 tightly structured with a one-line summary followed by a compact Args list and a Returns block. Every sentence earns its place — the truncation warning is the only additional prose, and it's essential. No filler or redundancy.

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 filtered-list read tool with 3 optional parameters and no output schema, the description comprehensively covers purpose, all parameters, return envelope structure, and the truncation edge-case behavior. The return format is explicitly documented even without an output schema, making this complete for agent invocation.

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?

With 0% schema description coverage, the description fully compensates by explaining each parameter: action (pass/block/reject/rdr/nat filter with optional semantics), limit (max entries, default 200), and target (firewall target name, omit for default). The description adds meaning beyond the bare schema names, though the parameter list in the description doesn't explicitly map to the schema names it covers all three.

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 clearly states this tool reads recent firewall-log entries with an optional filter for pass/block. The '[READ]' prefix signals it's a read operation, and the resource (firewall log) is specific and distinct from the many sibling tools like rule_stats or states_table that query other firewall data.

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?

It explains the optional action filter and target parameter, and signals the tool is for reading log entries (vs. altering them). It doesn't explicitly name sibling alternatives or when-not-to-use cases, but the '[READ]' prefix plus clear filter semantics provides adequate usage context for a log-reading tool.

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