get_feature_scan

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

Even with annotations already marking this as read-only, idempotent, and non-destructive, the description adds substantial behavioral detail: it documents unit differences versus siblings, explains that automationRatio is a conservative floor, reveals the dual meaning of 'linked' between explicit links and title-marker links, and states the aggregation depth. Nothing in the description contradicts the annotations.

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 long but every section earns its place: the purpose is front-loaded, and the UNITS and IMPORTANT sections are clearly labeled warnings that prevent real misuse. It reads like a structured briefing rather than a rambling explanation.

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?

Despite missing an output schema, the description is unusually complete: it lists the main return categories, explains units, describes the nuanced interpretation of linked test cases, notes hierarchy aggregation, and states the Jira connection prerequisite. An agent has enough context to invoke this tool and interpret its results accurately.

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?

The schema already describes jiraKey fully at 100% coverage, so the baseline is 3. The description adds value beyond the schema by specifying the aggregation depth ('2 levels deep: epic→story→subtask') and by making clear that the single key drives the whole feature health result, including linked cases and autotest trends.

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 and resource: 'Get a comprehensive feature health scan by Jira issue key.' It then enumerates concrete return contents such as Jira context, coverage stats, linked test cases, and autotest trends. It also clarifies how this tool differs from other health-related tools by highlighting its unique unit convention and its aggregation of child issues.

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 description gives clear context for when this tool is appropriate, especially for 'comprehensive' feature health and multi-level issue aggregation. However, it does not explicitly say when to prefer siblings like get_coverage_gaps or run_health_check, aside from noting they return percentages rather than fractions. There are no explicitly stated exclusions.

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