scan_directory_with_syft

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

With no annotations, the description carries the full transparency burden. It discloses that only a summary is returned by default, that save_sbom=True writes to a .sbom directory, the output format options, the exact return dictionary structure, and the prerequisite that Syft must be installed (with installation commands). It does not explicitly state it is read-only/non-destructive, but the catalog/inventory language strongly implies it. This is rich behavioral context beyond the minimal, but not exhaustive enough for a 5.

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 front-loaded with a clear purpose statement. It uses headings, bullet points, and concise sections for behavior, parameters, returns, and installation. While the supported package list is long, it is useful and directly relevant to an SBOM tool. Every section serves a purpose, and the overall structure is easy to scan.

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 covers the purpose, usage context, parameters, return format, and installation prerequisites. It differentiates the tool from vulnerability scanner siblings and explains the downstream use of the generated SBOM. Given the tool's moderate complexity, this is sufficiently complete for an agent to invoke it correctly, though it could mention edge cases like nonexistent directories or recursive scanning behavior.

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 baseline is 3. The description's Args section largely repeats the schema descriptions, adding only minor clarifications like 'relative or absolute' for directory_path and spelling out the output_format options (which are already in the schema). This adds marginal value beyond the schema, so a 3 is appropriate.

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 opens with a clear, specific statement: 'Scan an entire project directory with Syft to generate Software Bill of Materials (SBOM).' It explicitly distinguishes the tool from vulnerability scanners, which is a key differentiator among the many scanning siblings. The verb and resource are precise, leaving no ambiguity about what the tool does.

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 clearly states this is for generating an SBOM inventory, not for vulnerability scanning, and even suggests using Grype later for vulnerability scanning. It gives clear context on when to use the tool, but it doesn't explicitly name sibling alternatives or state exclusions (e.g., 'use scan_directory_with_grype for vulnerabilities'). This is a clear context without explicit alternative naming, matching a 4.

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