scan_portas_nmap

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

No annotations are provided, so the description carries the full burden. It only states that it performs port scanning using Nmap, but does not disclose that this involves active network traffic, potential IDS detection, or that it may be intrusive. The stealth parameter hints at configurable evasiveness, but the description itself does not warn about side effects or safety considerations. This is a significant gap for a tool that actively probes a target.

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 exceptionally concise: two short sentences that front-load the core purpose and usage. Every word earns its place, with no redundant details or filler. It perfectly balances brevity with essential information.

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?

Given the tool's complexity (3 parameters, output schema present) and lack of annotations, the description is minimal but covers basic usage. It states what it does and when to use it, but does not explain the output format (though covered by output schema) or the implications of the stealth parameter. For a first-phase scanner, it is adequate but could be more complete by mentioning that it is an active scan with potential detection risks.

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 covers all parameters (100% coverage), with descriptions like 'Flags do Nmap (convertidas via shlex, sem interpretação de shell)' and 'IP, hostname ou CIDR'. The description adds no extra meaning beyond the schema, so a baseline of 3 is appropriate. It does not provide examples or additional context that would enrich 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 'Realiza varredura de portas usando Nmap' (Performs port scanning using Nmap), which clearly identifies the action (scanning) and the resource (ports). It distinguishes from siblings by specifying port scanning as opposed to directory, vulnerability, or other scans. The phrase 'Use SEMPRE como primeira fase' adds context that this is the initial phase, reinforcing its unique role.

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 explicit usage guidance: 'Use SEMPRE como primeira fase' (Always use as first phase). This tells the agent when to use the tool, positioning it as the mandatory first step in a pentest sequence. It does not name alternatives or explicitly say when not to use, but the strong directive is sufficient for a clear usage context.

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