fix(health): steer agents to the weakest dimension

crates/tracedecay-graph-query/src/health.rs

@@ -559,7 +559,7 @@ pub struct HealthDimensions {
 /// Formula: `(product of all 5).powf(1.0/5.0) * 10000.0`, rounded.
 /// Zero in any dimension → 0.
 /// A low-weight multiplicative penalty for `coverage_discipline` reduces
-/// the score by up to 10% when skip-test-coverage is overused.
+/// the score by up to 2% when skip-test-coverage is overused.
 pub fn compute_composite_health(dims: &HealthDimensions) -> u32 {
     let product = dims.acyclicity * dims.depth * dims.equality * dims.redundancy * dims.modularity;
 
@@ -568,7 +568,6 @@ pub fn compute_composite_health(dims: &HealthDimensions) -> u32 {
     }
 
     let base = (product.powf(1.0 / 5.0) * 10_000.0).round();
-    // Low-weight penalty: skip-test-coverage overuse reduces score by up to 2%.
     let penalized = base * (0.98 + 0.02 * dims.coverage_discipline);
     penalized.round() as u32
 }
@@ -654,6 +653,30 @@ mod tests {
         );
     }
 
+    #[test]
+    fn skip_test_coverage_overuse_costs_at_most_two_percent_of_the_signal() {
+        let perfect = HealthDimensions {
+            acyclicity: 1.0,
+            depth: 1.0,
+            equality: 1.0,
+            redundancy: 1.0,
+            modularity: 1.0,
+            coverage_discipline: 1.0,
+        };
+        let every_function_skipped = HealthDimensions {
+            coverage_discipline: 0.0,
+            ..perfect.clone()
+        };
+        let half_skipped = HealthDimensions {
+            coverage_discipline: 0.5,
+            ..perfect.clone()
+        };
+
+        assert_eq!(compute_composite_health(&perfect), 10_000);
+        assert_eq!(compute_composite_health(&half_skipped), 9_900);
+        assert_eq!(compute_composite_health(&every_function_skipped), 9_800);
+    }
+
     #[test]
     fn dependency_depth_limits_after_ranking_all_components() {
         let mut adjacency =

crates/tracedecay-mcp-catalog/src/definitions/analysis.rs

@@ -195,7 +195,7 @@ pub(super) fn def_health(input_schema: Value) -> ToolDefinition {
     def(
         "tracedecay_health",
         "Health Score",
-        "Get quality signal (0-10000) with root cause breakdown (acyclicity, depth, equality, redundancy, modularity). Quality signal = geometric mean of 5 dimensions, maximize this ONE number.",
+        "Get quality signal (0-10000): the geometric mean of acyclicity, depth, equality, redundancy, and modularity, reduced by up to 2% for skip-test-coverage overuse. One weak dimension drags the whole signal down (a zero zeroes it), so pass details=true for the per-dimension breakdown and fix the lowest-scoring dimension instead of chasing the composite.",
         input_schema,
     )
 }

crates/tracedecay-mcp-catalog/src/definitions/tests.rs

@@ -107,6 +107,39 @@ fn health_read_accepts_the_empty_argument_object_on_every_surface() {
     assert!(request.matches(ApplicationSurfaceOperation::HealthRead));
 }
 
+/// Agents read tool descriptions as instructions. The health description
+/// must steer them to the per-dimension breakdown it advertises, not to
+/// maximizing the composite that hides which dimension failed.
+#[test]
+fn health_description_points_agents_at_the_weakest_dimension() {
+    let definition = get_tool_definitions()
+        .expect("tool definitions")
+        .into_iter()
+        .find(|definition| definition.name == "tracedecay_health")
+        .expect("health is advertised");
+    let description = definition.description.to_lowercase();
+
+    assert!(
+        !description.contains("maximize"),
+        "health must not tell agents to maximize the composite: {description}"
+    );
+    assert!(
+        description.contains("pass details=true")
+            && description.contains("fix the lowest-scoring dimension"),
+        "health must send agents to the per-dimension breakdown: {description}"
+    );
+    assert_eq!(
+        definition.input_schema["properties"]["details"]["type"],
+        json!(["boolean", "null"]),
+        "the details flag the description names must be advertised: {}",
+        definition.input_schema
+    );
+    assert!(
+        description.contains("up to 2%"),
+        "health must state the coverage-discipline penalty the score applies: {description}"
+    );
+}
+
 #[test]
 fn handle_gated_feedback_reads_are_advertised_with_their_request_handle() {
     let definitions = get_tool_definitions().expect("tool definitions");