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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description adds substantial behavior beyond them: the assessed/partial/not_assessed/error status vocabulary with reason codes, the guarantee that an empty result is never a pass, the dependency_graph_not_indexed downgrade, and the partial-with-fraction behavior of committed_secrets. It also discloses that a failed AI review reports not_assessed rather than a pass, which is exactly the kind of silent-failure behavior an agent needs.

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 key claim is front-loaded, but the body is a dense run-on list and the 'honest call' / 'we never looked' framing is repeated more than once. The emphasis on never-reporting-empty-as-pass could be stated once instead of threaded through three separate sentences.

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?

There is no output schema, so the description carries the return-value burden and does so: it specifies the per-category status enum, reason codes, and the fixed-version content of advisories. For a multi-source read-only scan this is complete enough for an agent to interpret results correctly.

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%, so the schema already documents all five parameters, including the ref/advisory-commit mismatch downgrade and the max_candidate_lines prefilter. The description adds little parameter-level meaning beyond restating coverage categories, so the baseline 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 specific verb+resource (security scan of a repository) and enumerates exactly what is covered: OSV.dev CVE/GHSA advisories against the indexed dependency graph, the supplemental advisory list, a committed-secret scan, and an optional Claude semantic review. It explicitly names the sibling it differs from (merjax_repo_health), so an agent can distinguish it without opening the schema.

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?

It gives clear context for use and names merjax_repo_health as the contrasting tool, and it explains the cost/benefit tradeoff of opting into include_ai_review (an Anthropic call, adds seconds). It stops short of an explicit 'use this when / do not use this when' rule set, so it is a strong 4 rather than a 5.

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