security

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

No annotations are provided, so the description must carry full behavioral disclosure burden. It mentions scan may return coverage guidance, but critically fails to disclose that the fix action with apply=true performs destructive file modifications, or that redact is preview-only (per schema) vs destructive. No mention of auth requirements or rate limits.

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?

Two sentences with no filler. Front-loaded with action list. However, extreme brevity leaves insufficient room to cover 16 parameters and 4 distinct action modes adequately.

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?

Severely underspecified for a 16-parameter multi-modal tool. With no annotations, no output schema, and four distinct action modes (file-based scanning vs content analysis vs redaction preview vs auto-fixing), the two-sentence description leaves critical gaps in explaining action-specific requirements, returns, and side effects.

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 description coverage is 100%, establishing a baseline of 3. The description references 'include globs' and 'includeHidden=true' which map to specific parameters, but adds no semantic detail beyond the schema's own descriptions (e.g., no guidance on trade-offs between outputFormat choices or scanType selection).

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 enumerates four specific security actions (scan, risk, redact, fix) and identifies the domain as 'Security actions'. It specifies the resource type and operations available, though it lacks explicit differentiation from siblings like find_and_fix or analyze_file.

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?

Provides specific guidance only for the scan action (using include globs and includeHidden=true for narrow scope), but offers no guidance on when to use risk vs scan, when to use fix vs redact, or when to choose this tool over sibling tools like find_and_fix or analyze_file.

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