opnsense_list_dhcp_leases

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.

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.

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.

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.

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.

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.