Launch Sn1per scan

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

Annotations already declare destructive/openWorld/non-idempotent, and the description adds material context beyond them: the scan runs with root privileges, sends real traffic to the target, out-of-scope targets are refused *and logged*, and Sn1per may query third-party services and scan live hosts it discovers within a range. It also sets duration expectations (minutes to hours) and gives a recovery path if the job handle is lost.

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 core action and the authorization constraint are front-loaded, and every sentence carries operational weight (scope refusal, defaults, polling cadence, job-handle recovery). It is dense though — the trailing scan_status guidance is valuable but makes the block longer than strictly needed for a launch tool.

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?

For a destructive, open-world, non-idempotent scan launcher with no output schema, the description covers what an agent must know: what it returns, that it runs asynchronously, that authorization is a precondition, what to do on refusal, how to poll, and how to recover a lost job id. Nothing essential is left to inference.

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 description coverage is 100%, so target formats, port requirements, workspace pattern and mode enum are already documented. The description only adds a soft usage nudge toward the stealth default and a gating note that brute-force/exploitation modes require operator enablement — useful, but not per-parameter meaning beyond the schema. Baseline 3 applies.

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?

States a specific verb and resource ('Start an ACTIVE Sn1per scan of one target') plus the immediate return value ('return a job handle immediately'). It also separates itself from async siblings by explaining the scan continues in the background, so an agent knows this is a fire-and-launch operation rather than a blocking one.

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?

Explicit when-to-use constraints ('only call this for targets the operator has explicitly authorized'), defaults ('use the default mode stealth unless the operator asks for more'), and hard exclusions ('do not retry with alternate spellings, encodings, IP forms or wider ranges - ask the operator'). It also routes to alternatives: sniper_status for mode semantics and scan_status(job_id) for polling, with pacing guidance ('every few minutes, not in a loop').

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