network_list_wans

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

With no annotations, the description carries the full burden. It states it lists WAN interfaces (implying a read-only operation) and describes pagination parameters, but does not explicitly confirm safety or disclose potential side effects. It lacks details on authorization requirements or behavior with invalid site IDs.

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 concise, with a single sentence for the purpose followed by a compact parameter list. Every sentence adds value, and the format is easily scannable. There is no unnecessary verbiage.

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?

The tool has an output schema, so the description need not detail return values. It covers the main task and parameter semantics. However, it omits any mention of prerequisites (e.g., user permissions) or error conditions (e.g., invalid site_id). This is a minor gap for a list tool.

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 has 0% description coverage, so the description compensates by documenting all three parameters with meaningful explanations: site_id is 'the site ID', offset is 'pagination offset', limit is 'items per page' with default 25 and max 200. This adds significant value beyond the schema's type information.

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 WAN interfaces on a local UniFi site. The verb 'List' and specific resource 'WAN interfaces' make the purpose unambiguous, distinguishing it from sibling tools like network_list_devices or network_list_clients.

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. It does not mention prerequisites, fallback tools, or scenarios where another tool might be more appropriate. For example, it doesn't explain that this tool is for WAN-specific monitoring while network_list_devices covers all network interfaces.

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