find_vlan_for_ip

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

No annotations are provided, so the description carries full burden. It explains input format but does not disclose behavioral traits such as whether the tool is read-only, error handling for invalid IPs, what happens if no match, or performance characteristics.

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 short and front-loaded with the purpose. It includes a concise example. The example could be better integrated or formatted, but overall it is efficient without superfluous text.

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 2 required parameters and no output schema. The description explains input format well but does not describe the return value (e.g., what is returned: matched VLAN ID? Subnet? Both?). It also does not address edge cases like multiple matches or no match. Given the simplicity, the gap in output coverage is notable.

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 0% (no parameter descriptions in schema). The description compensates by explaining the vlan_map format via example: keys are VLAN IDs (strings), values can be a CIDR string or an object with 'cidr' and 'name' fields. However, it does not detail allowed IP formats (e.g., IPv6) or constraints.

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's purpose: 'Find which VLAN subnet(s) match an IP in a provided VLAN map.' It uses a specific verb ('Find') and resource ('VLAN subnet(s)'), and the example with VLAN map format distinguishes it from siblings like ip_in_subnet or ip_in_vlan.

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 labels it as a 'Tier 1 hero tool' and provides an example question ('What VLAN does this IP belong to?'), which implies usage context. However, it does not explicitly compare to siblings like ip_in_vlan or provide when-to-use vs. when-not-to-use guidance.

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