full_health_scan

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

No annotations exist, so the description carries the behavioral burden. It clearly defines the operation as a scan, enumerates the analysis categories, and states the return contract: a 0–100 overall health score and prioritized findings. It does not mention side effects or repository-clone behavior for URLs, but for a read-only scanning tool the disclosed behavior is substantial.

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 description is a single, dense sentence that front-loads the core action and immediately states the output format. Every word contributes; there is no repetition or filler.

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 one-parameter tool with no output schema, the description adequately explains the return shape, but it leaves the relationship to the four sibling scanners implicit and says nothing about how an omitted repo_path should be handled even though the schema marks it optional. This is adequate but with clear gaps for an aggregation tool.

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%, and the sole parameter repo_path already has a clear description ('Path or URL to the repository'). The tool description adds no parameter-specific nuances, so the baseline score of 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 is specific and informative: it names a verb ('Run'), a resource ('complete codebase health scan'), and the four concrete scan dimensions (dead code, circular dependencies, coupling metrics, architectural drift). This clearly differentiates this aggregator from its single-concern siblings.

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?

The usage context is implied rather than explicit: the word 'complete' and the listed scan areas suggest this tool subsumes the sibling analyses, but it never states when to choose full_health_scan over analyze_dead_code, detect_circular_deps, or the others. No exclusion or alternative guidance is included.

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