nmap_os_detection

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

Behavioral transparency is limited. The description discloses the sudo behavior ('Automatically uses sudo if not root'), which is useful, but it does not mention that OS detection sends packets, may be noisy/slow, or what output format to expect. With no annotations, the description carries the full burden and falls short.

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 no filler. It front-loads the core purpose and then provides two key operational facts: sudo auto-elevation and acceptable target formats. Every sentence earns its place.

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 no output schema and no annotations, the description should explain more about the scan's behavior, output, and potential impact. It only covers target syntax and privilege handling, leaving significant gaps for a network scan tool that may have security and performance implications.

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 single parameter 'targets' is given meaning by the description: 'IPs/ranges/hostnames'. This adds value beyond the bare schema, which lacks any description. However, it could be more detailed (e.g., examples of range notation like CIDR or hyphenated ranges), but for one parameter it is sufficient.

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 function: 'OS detection scan (-O)' – a specific verb and resource. It is unambiguously distinguished from sibling nmap tools like port scan, service detection, or vulnerability scan by explicitly naming OS detection and the -O flag.

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?

No guidance on when to use this tool versus alternatives such as nmap_port_scan or nmap_service_detection. The description only provides what the tool does, not when to choose it. It does not mention exclusions, prerequisites, or preferred scenarios.

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