scan_diff_for_secrets

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

With no annotations, the description carries the full burden: it discloses the detection categories and the return artifact (replacement .env diffs), which is genuinely useful. It does not state that the operation is non-mutating/read-only, whether findings include line numbers or severity, or how false positives/high-entropy matches are handled.

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?

One dense sentence, front-loaded with the verb and scope, with the detection list and output type attached without filler. Every clause earns its place and nothing is redundant.

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 single-parameter, read-only analysis tool with no output schema, the description covers input expectations and the shape of the result (replacement diffs) well enough to call it. Missing only the reporting details (line references, severity, empty-result behavior) that an agent would want before relying on the output.

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% with a single required parameter, so the schema already defines that a unified git diff goes in. The description adds only a slight nuance by emphasizing 'added' lines are scanned, which implies context lines are ignored; nothing beyond that is contributed.

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?

States a specific verb ('scans') plus resource ('added git diff lines') and enumerates the credential families it detects, then names the deliverable ('.env replacement diffs'). It is unmistakably distinct in intent from review_git_diff, but never names or contrasts with that sibling, so differentiation is inferred rather than stated.

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?

No when-to-use / when-not-to-use guidance and no mention of the sibling tools (review_git_diff, generate_github_pr_suggestions) that an agent must choose between. The only usage signal is 'added git diff lines', which narrows scope but does not tell the agent when this tool is the right pick.

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