Validate audit coverage and independent reviewer checks, then generate a target-neutral Markdown security report from structured findings.
Phase 6: validate coverage and separate reviewer checks, then generate target-neutral Markdown reports.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes | ||
| findings | Yes | ||
| repository | Yes | ||
| scope_paths | Yes | ||
| coverage_ledger | Yes | ||
| requested_status | Yes | ||
| independent_checks | Yes | ||
| inventory_complete | Yes |
Changes observed during successful MCP inspections.
v0.3.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It says reports are "generated" but not whether anything is written to disk, where output lands, whether the call fails on invalid coverage or low-quality reviewer checks, or whether it is idempotent — all critical for a mutation-flavored generation step.
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?
A single compact sentence with the phase marker front-loaded and no filler. It is efficient, though its brevity is also the source of the missing detail rather than a model of disciplined density.
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 an 8-parameter, all-required tool with nested arrays, zero schema documentation, no annotations and no output schema, the one-line description leaves far too much unresolved — notably what the tool emits, where, and how its internal validation differs from the dedicated validator siblings.
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 0% across 8 required parameters, including structurally complex ones like coverage_ledger, independent_checks and the three-variant findings union. The description only obliquely gestures at two of them ("coverage", "reviewer checks") and adds no meaning about required contents, verdict variants, or what requested_status/inventory_complete control.
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 names a concrete output ("target-neutral Markdown reports") and places itself as "Phase 6", which is more specific than a tautology. But it also claims to "validate coverage and separate reviewer checks", which is the apparent job of siblings like audit_coverage_validate, audit_findings_validate and audit_independent_verify, so an agent cannot tell from the text what is unique to this tool.
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?
"Phase 6" implies an ordering constraint relative to earlier audit phases, which is real usage guidance not present in the schema. However, there is no explicit statement of when to prefer this tool over the several validate/verify siblings, nor any precondition such as what state the ledger and findings must be in first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.