Health report

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: this is a multi-analysis aggregation in a single call (implying cost/latency beyond the individual tools) and it returns a {"markdown": ...} payload rather than structured rows. It does not mention any timeouts or partial-failure behavior for a composite call, which keeps it from a 5.

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?

Front-loads the deliverable, then the composition list, then the routing advice, then the return shape — a sensible ordering with no filler. The middle sentence runs long with its embedded 'AND are orphaned, single-owner or strongly coupled' qualifier, which costs a little scannability.

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 five-parameter composite tool with an output schema present and full schema coverage, the description supplies everything an agent needs to choose it over siblings and predict its shape: what it aggregates, what the headline list means, when to prefer the individual tools, and that the result is Markdown. No material gaps remain.

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 each of the five parameters (top, since, max_files, repo_path, inactive_after) is documented inline including defaults and git-date syntax. The description adds no parameter-level detail beyond that, so this sits at the baseline for a fully documented schema.

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 concrete deliverable (a one-call Markdown health report) and enumerates exactly which analyses it composes: repo_summary, hotspots, change_coupling, bus_factor, knowledge_risk. The definition of the 'what to look at first' heuristic (files that change often AND are orphaned, single-owner or strongly coupled) tells an agent precisely what makes this output actionable rather than just a bundle of the sibling tools.

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?

Explicitly routes the agent: 'Use it for an overview; use the individual tools to dig into details.' The alternatives it points at are named sibling tools that appear in the composition list, so the when-to-use vs when-not-to-use split is unambiguous.

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