scan_directory_with_checkov

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

The description discloses prerequisites (Checkov must be installed), supported file types, and return type. However, it fails to explain the behavioral implication of the return_output parameter (default false saves output to file), which creates ambiguity about the actual output behavior. With no annotations, this gap leaves significant behavioral disclosure unmet.

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 thorough but contains some redundancy (first two sentences both say it scans IaC files). The file type list and install note are useful, and the structure with clear headings helps readability. It is longer than strictly necessary but not bloated.

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 moderate complexity and the presence of an output schema, the description covers key aspects: purpose, scope, supported formats, and installation requirement. It misses explaining the default file-saving behavior tied to return_output, but the overall context is sufficient for an agent to use the tool effectively.

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 coverage is 100%, so the schema already documents all three parameters. The description redundantly restates directory_path and severity_threshold but adds no additional semantic detail beyond the schema. It omits return_output entirely, so no added value for that parameter.

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 a specific action and resource: 'Scan an entire project directory with Checkov for IaC security issues.' It immediately distinguishes itself from sibling tool scan_with_checkov, which scans code snippets, making the purpose unambiguous.

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 contrasts with scan_with_checkov ('Unlike scan_with_checkov which scans code snippets'), offering a clear alternative. It also lists supported file types to indicate applicable scenarios. However, it does not provide explicit when-not-to-use guidance relative to other sibling scanners like semgrep or trivy.

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