guardvibe

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

With no annotations provided, the description carries the full burden. It explains the git diff behavior and notes that findings are returned 'only for modified/added files' (excluding deletions). However, it fails to disclose what type of scan is performed (security? linting?), which is critical context given the security-focused sibling tools (scan_secrets, scan_dependencies).

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?

Three sentences with zero waste. Front-loaded with the core constraint ('Scan only files that have changed'), followed by use cases, then return behavior. Every sentence earns its place.

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 3-parameter schema with 100% coverage and no output schema, the description adequately covers the git mechanics and use cases. However, it has a clear gap: it doesn't specify the scan domain (security vulnerabilities, secrets, general linting), which is necessary for an agent to know if this tool fits their needs.

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%, establishing a baseline of 3. The description adds value by elaborating on the 'base' parameter with concrete git ref examples: '(branch, commit, or HEAD~N)'. This clarifies the expected input format beyond the schema's generic 'Git ref' description.

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 defines the tool's specific scope: scanning files changed since a git ref (branch, commit, or HEAD~N). The phrase 'Scan only files that have changed' effectively distinguishes it from siblings like scan_directory (full scan) and scan_file (single file) by emphasizing the git-diff-based filtering.

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 explicit use cases: 'Ideal for PR checks, pre-push hooks, and incremental CI.' This gives clear context for when to use the tool. However, it stops short of explicitly naming alternatives (e.g., 'use scan_directory for full repository scans') or stating when not to use it.

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