dhcp_static_mappings

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

No annotations are provided, so the description carries the burden. The '[READ]' prefix signals a non-mutating operation, and the description discloses it's a read/list operation. However, it doesn't explain what happens with the optional target (error vs default firewall), whether any special permissions are needed, or the return format structure. The behavioral disclosure is adequate but thin.

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 extremely short (two lines plus an Args section). The '[READ]' prefix is an efficient signal. No wasted words. It's concise and front-loaded, though the args explanation could be slightly more detailed without hurting conciseness.

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 simple one-parameter read tool, the description is near-minimal. There's no output schema, so return format isn't disclosed. With 18+ sibling tools including the closely related dhcp_leases, a bit more context distinguishing this from dhcp_leases would help. The description is adequate for a trivial list tool but leaves some gaps.

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%, and the single parameter 'target' is only described as 'Firewall target name from config; omit for the default.' This does add practical guidance (omit for default), which is useful beyond the raw schema. However, it doesn't explain where 'target' values come from or the format expected, so it only partially compensates for zero coverage.

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 states 'DHCP static (reserved) mappings (MAC ↔ IP)' using a specific noun+resource. It's a clear read-oriented listing tool. It doesn't explicitly differentiate from the sibling dhcp_leases tool, which could be ambiguous to an agent, but the '[READ]' prefix and the MAC↔IP wording make the purpose reasonably clear.

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 explains when to use it implicitly via '[READ]' prefix and the 'reserved mappings' wording, and explains the optional target parameter. However, it doesn't distinguish when to use this vs dhcp_leases (active leases vs static reservations), and provides no exclusions or alternatives.

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