Quarantine Scan Dir Tool

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

No annotations are provided, so the description must carry the behavioral transparency burden. It explains what the scan detects and that it runs L1+L2, which is useful, but it does not explicitly state whether the operation is read-only, whether files are quarantined or modified despite the tool name, or what permissions/limitations apply.

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 front-loaded with a clear purpose, then expands with the threat model and usage context. The middle sentence is long but most of its content is substantive; there is no filler, though it could be tightened slightly.

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 one-parameter scan tool with an output schema, the description covers what is scanned, why it is dangerous, and when to run it. The remaining gaps are explicit side-effect disclosure and differentiation from similar sibling scan tools, which are partially addressed by the clear usage instruction and the tool name.

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 fully documents the single 'directory' parameter, so the description does not need to repeat basic semantics. The description adds contextual color by indicating the kind of directories that warrant scanning, but it provides no additional format, constraint, or validation details beyond 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 states a specific verb and resource: 'Scan a directory for Python module shadowing attacks and obfuscated code.' It also names concrete detection targets (stdlib shadowing, L1+L2 injection), which clearly distinguishes it from generic content scanning tools and from the file-level quarantine_scan_tool sibling.

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?

It gives an explicit when-to-use instruction: 'Use this BEFORE running any Python code in a directory extracted from an archive, cloned from an untrusted repo, or downloaded from the web.' However, it does not mention when not to use it or explicitly compare it with similar sibling scan tools, so it lacks a complete routing rule.

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