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

Annotations cover safety and idempotency, but the description adds substantial behavioral context: normalization of host bits, counting overlaps once, exact output fields (cidrs, normalizedInclude, normalizedExclude, counts), the error behavior for >10000 output CIDRs (error without partial result), and issue reporting by include/exclude index. It also distinguishes remote vs. browser execution.

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 dense but front-loaded with the core purpose and use case. Sentences are information-rich and each earns its place, though the volume of detail may be slightly more than necessary for an agent to select the tool. No redundant padding.

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?

With an output schema present, the description needn't explain return values, but it still lists output fields and error conditions, which is helpful. It covers constraints, edge cases (complete removal, too many outputs), error reporting, execution model, and explicit exclusions. Complete for an agent to invoke correctly.

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 descriptions cover 100% of parameters, so baseline is 3. The description adds meaning by explaining the semantic relationship between include and exclude ('union(include) minus union(exclude)'), noting that exclude may be empty, and that normalization applies to inputs. It doesn't add syntax details beyond what the schema provides, but enriches conceptual understanding.

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 a specific operation ('Compute union(include) minus union(exclude) as a minimal sorted canonical CIDR list') and names a concrete use case ('prepare WireGuard AllowedIPs exceptions'). It clearly distinguishes itself from siblings like cidr-cover and range-to-cidrs through the set-subtraction semantics.

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 clear when-to-use context ('prepare WireGuard AllowedIPs exceptions or calculate remaining address space') and constraints ('one address family', 'nonempty include list', 'at most 1000 entries'). It also clarifies what it does NOT do ('does not inspect live allocation, configure WireGuard, or change firewall rules'), but it does not explicitly route to alternative tools for other scenarios.

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