scan_ports

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

No annotations are provided, so the description must bear the full burden of behavioral disclosure. It discloses the 20-port limit but omits other relevant behaviors such as timeout handling, scan methodology (e.g., TCP connect vs SYN), or potential intrusiveness. The description does not contradict any annotations since none exist.

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, front-loaded sentence that conveys the core function and a key constraint without wasted words. Every element earns its place, making it highly concise and efficiently structured.

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 no output schema and no annotations, the description leaves out return value format, error handling, and scan specifics. However, for a relatively simple tool with only two parameters, this minimal description is barely adequate, though it could do more to clarify outcomes.

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 schema has 50% coverage (ports has a description, host does not). The description adds the 'up to 20 ports' constraint for the ports parameter and clarifies that the target is a host, but it does not elaborate on host format or what 'common ports' means. This is a moderate addition over the schema.

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 action ('Scan') and object ('ports on a host'), making the tool's purpose unambiguous. It distinguishes itself from sibling network tools like dns_lookup and whois_lookup by focusing specifically on port scanning. The 'up to 20 ports' limit is an additional useful constraint that does not obscure the core purpose.

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 like dns_lookup, http_headers, or whois_lookup. It does not mention any prerequisites, such as host reachability or scan type, and only hints at the 20-port limit, which is more a constraint than usage guidance.

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