scan

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

No annotations are present, so the description carries the full burden. It describes the pipeline of extraction and detection but does not explicitly state that it is a read-only operation, nor does it disclose potential side effects like file modifications or permission requirements. The description is adequate but lacks specificity about safety and behavior beyond the pipeline.

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 two sentences plus a code-like reference, all front-loaded. The first sentence captures the entire pipeline, the second explains it's a wrapper, and the third clarifies return format. No wasted words; every sentence adds value.

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 convenience wrapper tool, the description is fairly complete: it explains the pipeline, the equivalent call, and the return shape. It does not mention output schema (which is absent) but that is acceptable as per rules. However, it could offer more context on when to choose this over find_secrets or extract_strings, but the sibling list and description suffice for typical use.

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 input schema has 0% description coverage, so the description must compensate. It does so by referencing the equivalent function call find_secrets(path, detector_set='all', max_per_category=...). This clarifies that max_per_category controls limits per category and defaults to 200, adding semantic value 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 clearly states the tool performs a full pipeline: extract strings, apply all detectors, return findings. It distinguishes itself from siblings by being a convenience wrapper for the typical workflow, with specifics like detector_set='all'.

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 indicates this tool is for the typical workflow and is a convenience wrapper, implying use when a complete scan with all detectors is desired. It references find_secrets as an equivalent but more granular alternative, providing some usage guidance. However, it does not explicitly list when-to-use vs when-not-to-use or compare to other siblings like extract_strings.

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