List network interfaces

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

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds value by warning that the full listing is very large and that summary detail is the default, which helps the agent anticipate response size. It also mentions the fields returned. No contradiction with annotations.

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 a single, efficiently structured sentence. It front-loads the purpose and scope, then adds a key behavioral hint about default detail. No filler or redundancy; every piece of information is necessary.

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?

Without an output schema, the description partially compensates by naming the fields returned (link state, address, default route) and the default detail level. It does not mention pagination or handling of large results beyond the default, but the schema already defines a limit parameter. Given the simplicity of the tool, this is adequate but could hint at using limit for large listings.

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 coverage is 100%, so each parameter is already documented with descriptions and enums. The description does not introduce additional parameter semantics beyond what the schema provides, so the baseline of 3 applies. It mentions fields returned but not parameter-specific details.

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 the tool lists every interface on the router, enumerating types (WAN, bridges, Wi-Fi, VPN) and the included attributes (link state, address, default route). This distinguishes it from siblings like get_interface or list_devices, though it doesn't explicitly name an alternative. The verb 'list' and resource 'interfaces' are specific.

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 provides no guidance on when to use this tool versus alternatives such as get_interface for a single interface or list_vpn for VPN-specific listings. It only notes the default detail level, which is more about output behavior than usage context. No exclusions or alternative routing is given.

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