Bbot Scan

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

Beyond the readOnlyHint annotation, the description discloses key behaviors: it can return inline if the scan finishes within wait_seconds, otherwise it returns a job_id and directs to poll with job_status and read with fetch_slice. This is valuable operational behavior not captured by annotations.

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 well-structured and concise: one sentence for purpose, a compact list of presets, a sentence about aggressive presets routing, and a clear explanation of return semantics. No fluff or unnecessary detail.

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 description provides essential context for choosing this tool over similar siblings: it names the aggressive presets that go to bbot_scan_active and explains the inline vs. job_id return mechanism. It also positions the tool as the primary recon entrypoint, which is sufficient for an agent to decide when to invoke it.

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 description explains the preset parameter by listing its valid values and mentions wait_seconds behavior. However, it does not explain the modules parameter (what modules can be specified) or max_events (its purpose or effect). With 0% schema description coverage, these gaps leave the agent partially uninformed about two parameters.

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 maps attack surface via BBOT and identifies it as the primary recon entrypoint. It distinguishes from the sibling bbot_scan_active by specifying which presets are routed there.

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 explicitly lists the available presets and the default, and explains that aggressive presets are routed to bbot_scan_active which requires approval. It also explains the return behavior and how to poll and read results, giving clear guidance on when to use this tool.

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