Quantified Self MCP Server

Overview Schema Source Related Servers Discussions Admin

Find correlation between two metrics

find_metric_correlation

Read-onlyIdempotent

Compute the Pearson correlation between two different metrics over a date range to see whether they move together, not whether one causes the other.

Instructions

Compute the Pearson correlation between two metrics over the same window, joined by date. Correlation, not causation: a strong r just means the two moved together, not that one caused the other. A question phrased causally ("does my sleep affect my mood?") still gets only this association. The result does not show that one metric affects or causes the other, so report r, n and the wording the claim allows, and say nothing stronger.

Use this tool when:

the user names or implies two different metrics and asks whether they move together (e.g. "does my sleep affect my mood?", "do days with more workout minutes tend to have a higher HRV?").

Do not use this tool when:

only one metric is in question -> use get_baseline, calculate_metric_trend, or detect_metric_anomalies instead, depending on what's being asked about that one metric.
the question is why one metric looked the way it did on a specific date -> use explain_metric_change, which already reports the other metrics that correlate with it.
the question is whether one metric differs between two time periods (e.g. before vs. after a date) -> use compare_metric_periods.

Reading the result: report what was observed (r, n, and how many days of each metric were present) separately from what may be claimed about it. Read claim.decision before reporting r. Its tier (insufficient, suggestive, detectable_not_meaningful or supported) is the strongest wording allowed, and a high r from a thin or gappy sample is capped there, not in r itself, so never judge a correlation from r alone. claim.decision.template is a sentence frame, not finished text: replace "..." with the finding, and {limiting_factors} with the must_state entries put into plain words. Those entries are codes, not sentences (practical_not_evaluated, for example, means that whether the difference matters in practice was not checked), so do not quote a code to the user. When data_health is not VALID, say why.

Privacy note: this server and its SQLite file are entirely local, but the data returned by this tool becomes part of the conversation sent to whatever model the calling client is configured with. If that model runs in the cloud rather than on your machine, treat this the same as pasting the data into a chat with that provider.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "metric_a": "<metric_a>",
      "metric_b": "<metric_b>"
    },
    "name": "find_metric_correlation"
  }
}

Input Schema

Name	Required	Description
`end_date`	No	Last day to include, formatted YYYY-MM-DD. Defaults to today.
`lag_days`	No	Shift metric_b this many days later before joining — 1 tests whether metric_a today predicts metric_b tomorrow (e.g. "does poor sleep tonight predict lower steps tomorrow?"). 0 (default) compares same-day values.
`metric_a`	Yes
`metric_b`	Yes
`start_date`	No	First day to include, formatted YYYY-MM-DD. Defaults to 90 days before end_date.

Output Schema

Name	Required	Description
`n`	Yes
`r`	No
`note`	No
`claim`	Yes	Evidence and decision for the correlation claim; read claim.decision before reporting it.
`lag_days`	Yes
`metric_a`	Yes
`metric_b`	Yes
`evidence_a`	Yes	DEPRECATED: identical to claim.evidence_a. Use claim.decision, not a standalone confidence field.
`evidence_b`	Yes	DEPRECATED: identical to claim.evidence_b. Use claim.decision, not a standalone confidence field.
`data_health`	No	Whether the data behind this result is complete and current (the weaker of the two metrics).

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.0.30Oct 13, 2026

addedOutput schema / properties / data_health

Added value: +{
+  "anyOf": [
+    {
+      "description": "Data-quality state behind one result (not a medical or statistical confidence score). status is one of\nVALID, VALID_WITH_GAPS, MIXED_SOURCES, INSUFFICIENT_DATA, STALE, IMPORT_INCOMPLETE; reasons lists every\ncondition that\napplies. See data_health.compose_data_health for how it is decided.",
+      "properties": {
+        "completeness": {
+          "properties": {
+            "coverage_ratio": {
+              "type": "number"
+            },
+            "expected_days": {
+              "type": "integer"
+            },
+            "missing_days": {
+              "type": "integer"
+            },
+            "observed_days": {
+              "type": "integer"
+            }
+          },
+          "required": [
+            "expected_days",
+            "observed_days",
+            "coverage_ratio",
+            "missing_days"
+          ],
+          "type": "object"
+        },
+        "coverage": {
+          "properties": {
+            "end": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null
+            },
+            "requested_end": {
+              "type": "string"
+            },
+            "requested_start": {
+              "type": "string"
+            },
+            "start": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null
+            }
+          },
+          "required": [
+            "requested_start",
+            "requested_end"
+          ],
+          "type": "object"
+        },
+        "freshness": {
+          "properties": {
+            "age_days": {
+              "anyOf": [
+                {
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null,
+              "description": "Days from the latest observation to the end of the requested window."
+            },
+            "dataset_days_behind": {
+              "anyOf": [
+                {
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null,
+              "description": "Days from the dataset's latest data (any metric) to today."
+            },
+            "latest_data": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null
+            }
+          },
+          "type": "object"
+        },
+        "gaps": {
+          "items": {
+            "properties": {
+              "days": {
+                "type": "integer"
+              },
+              "end": {
+                "type": "string"
+              },
+              "start": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "start",
+              "end",
+              "days"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "last_import": {
+          "anyOf": [
+            {
+              "properties": {
+                "finished_at": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "default": null
+                },
+                "importer": {
+                  "type": "string"
+                },
+                "source_file": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "default": null
+                },
+                "status": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "importer",
+                "status"
+              ],
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "last_successful_import": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "observations": {
+          "description": "Number of daily values the result is computed from.",
+          "type": "integer"
+        },
+        "reasons": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "status": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "status",
+        "reasons",
+        "freshness",
+        "coverage",
+        "completeness",
+        "gaps",
+        "observations"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Whether the data behind this result is complete and current (the weaker of the two metrics)."
+}

Changed3 schema fields changedv1.0.28Sep 30, 2026

removedOutput schema / properties / claim_decision

Removed value: -{
-  "deprecated": true,
-  "description": "DEPRECATED: identical to claim.decision. Use claim.decision instead.",
-  "properties": {
-    "must_state": {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "permitted_phrasing_class": {
-      "type": "string"
-    },
-    "template": {
-      "type": "string"
-    },
-    "tier": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "tier",
-    "permitted_phrasing_class",
-    "must_state",
-    "template"
-  ],
-  "type": "object"
-}

removedOutput schema / properties / evidence_profile

Removed value: -{
-  "deprecated": true,
-  "description": "DEPRECATED: identical to claim.profile. Use claim.decision instead.",
-  "properties": {
-    "analysis": {
-      "type": "string"
-    },
-    "dimensions": {
-      "items": {
-        "properties": {
-          "can_block": {
-            "default": true,
-            "type": "boolean"
-          },
-          "details": {
-            "additionalProperties": true,
-            "type": "object"
-          },
-          "dimension": {
-            "enum": [
-              "sample",
-              "temporal",
-              "robustness",
-              "missingness",
-              "practical",
-              "measurement_validity",
-              "provenance"
-            ],
-            "type": "string"
-          },
-          "reason_codes": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "status": {
-            "enum": [
-              "adequate",
-              "negligible",
-              "not_assessed",
-              "weak",
-              "concern",
-              "blocking"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "dimension",
-          "status"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "effect": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "metric": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "metric",
-    "analysis",
-    "dimensions"
-  ],
-  "type": "object"
-}

changedOutput schema / required

Previous value: -[
-  "metric_a",
-  "metric_b",
-  "lag_days",
-  "n",
-  "claim",
-  "evidence_a",
-  "evidence_b",
-  "evidence_profile",
-  "claim_decision"
-]New value: +[
+  "metric_a",
+  "metric_b",
+  "lag_days",
+  "n",
+  "claim",
+  "evidence_a",
+  "evidence_b"
+]

Changed21 schema fields changedv1.0.26Sep 25, 2026

addedOutput schema / properties / claim

Added value: +{
+  "description": "Evidence and decision for the correlation claim; read claim.decision before reporting it.",
+  "properties": {
+    "decision": {
+      "description": "How strongly this claim may be stated. tier is insufficient, suggestive, detectable_not_meaningful or supported; every entry in must_state has to be mentioned when reporting it.",
+      "properties": {
+        "must_state": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "permitted_phrasing_class": {
+          "type": "string"
+        },
+        "template": {
+          "type": "string"
+        },
+        "tier": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "tier",
+        "permitted_phrasing_class",
+        "must_state",
+        "template"
+      ],
+      "type": "object"
+    },
+    "evidence_a": {
+      "description": "Descriptive data coverage behind the first source.",
+      "properties": {
+        "confidence": {
+          "type": "string"
+        },
+        "coverage_ratio": {
+          "type": "number"
+        },
+        "expected_days": {
+          "type": "integer"
+        },
+        "freshness_days": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "gaps": {
+          "items": {
+            "properties": {
+              "days": {
+                "type": "integer"
+              },
+              "end": {
+                "type": "string"
+              },
+              "start": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "start",
+              "end",
+              "days"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "measurement_count": {
+          "type": "integer"
+        },
+        "missing_days": {
+          "type": "integer"
+        },
+        "observed_days": {
+          "type": "integer"
+        },
+        "observed_end": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "observed_start": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "recent_gap_days": {
+          "type": "integer"
+        },
+        "requested_end": {
+          "type": "string"
+        },
+        "requested_start": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "requested_start",
+        "requested_end",
+        "expected_days",
+        "observed_days",
+        "coverage_ratio",
+        "missing_days",
+        "measurement_count",
+        "gaps",
+        "recent_gap_days",
+        "confidence"
+      ],
+      "type": "object"
+    },
+    "evidence_b": {
+      "description": "Descriptive data coverage behind the second source.",
+      "properties": {
+        "confidence": {
+          "type": "string"
+        },
+        "coverage_ratio": {
+          "type": "number"
+        },
+        "expected_days": {
+          "type": "integer"
+        },
+        "freshness_days": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "gaps": {
+          "items": {
+            "properties": {
+              "days": {
+                "type": "integer"
+              },
+              "end": {
+                "type": "string"
+              },
+              "start": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "start",
+              "end",
+              "days"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "measurement_count": {
+          "type": "integer"
+        },
+        "missing_days": {
+          "type": "integer"
+        },
+        "observed_days": {
+          "type": "integer"
+        },
+        "observed_end": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "observed_start": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "recent_gap_days": {
+          "type": "integer"
+        },
+        "requested_end": {
+          "type": "string"
+        },
+        "requested_start": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "requested_start",
+        "requested_end",
+        "expected_days",
+        "observed_days",
+        "coverage_ratio",
+        "missing_days",
+        "measurement_count",
+        "gaps",
+        "recent_gap_days",
+        "confidence"
+      ],
+      "type": "object"
+    },
+    "profile": {
+      "description": "Per-dimension evidence quality behind this claim (sample, temporal, missingness, ...), assessed jointly across both sources where relevant. Dimensions without an evaluator yet are 'not_assessed' and cap the claim, never count as adequate.",
+      "properties": {
+        "analysis": {
+          "type": "string"
+        },
+        "dimensions": {
+          "items": {
+            "properties": {
+              "can_block": {
+                "default": true,
+                "type": "boolean"
+              },
+              "details": {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              "dimension": {
+                "enum": [
+                  "sample",
+                  "temporal",
+                  "robustness",
+                  "missingness",
+                  "practical",
+                  "measurement_validity",
+                  "provenance"
+                ],
+                "type": "string"
+              },
+              "reason_codes": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "status": {
+                "enum": [
+                  "adequate",
+                  "negligible",
+                  "not_assessed",
+                  "weak",
+                  "concern",
+                  "blocking"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "dimension",
+              "status"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "effect": {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        "metric": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "metric",
+        "analysis",
+        "dimensions"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "evidence_a",
+    "evidence_b",
+    "profile",
+    "decision"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / claim_decision / deprecated
```
Added value: +true
```

changedOutput schema / properties / claim_decision / description

Previous value: -"How strongly this result may be stated. tier is insufficient, suggestive, detectable_not_meaningful or supported; every entry in must_state has to be mentioned when reporting it."New value: +"DEPRECATED: identical to claim.decision. Use claim.decision instead."

removedOutput schema / properties / evidence_a / anyOf

Removed value: -[
-  {
-    "description": "Coverage/quality of the data a single-metric analytical result is\nbased on. See evidence.build_evidence for how each field is computed.",
-    "properties": {
-      "confidence": {
-        "type": "string"
-      },
-      "coverage_ratio": {
-        "type": "number"
-      },
-      "expected_days": {
-        "type": "integer"
-      },
-      "freshness_days": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "gaps": {
-        "items": {
-          "properties": {
-            "days": {
-              "type": "integer"
-            },
-            "end": {
-              "type": "string"
-            },
-            "start": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "start",
-            "end",
-            "days"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "measurement_count": {
-        "type": "integer"
-      },
-      "missing_days": {
-        "type": "integer"
-      },
-      "observed_days": {
-        "type": "integer"
-      },
-      "observed_end": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "observed_start": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "recent_gap_days": {
-        "type": "integer"
-      },
-      "requested_end": {
-        "type": "string"
-      },
-      "requested_start": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "requested_start",
-      "requested_end",
-      "expected_days",
-      "observed_days",
-      "coverage_ratio",
-      "missing_days",
-      "measurement_count",
-      "gaps",
-      "recent_gap_days",
-      "confidence"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / evidence_a / default
```
Removed value: -null
```
addedOutput schema / properties / evidence_a / deprecated
```
Added value: +true
```

addedOutput schema / properties / evidence_a / description

Added value: +"DEPRECATED: identical to claim.evidence_a. Use claim.decision, not a standalone confidence field."

addedOutput schema / properties / evidence_a / properties

Added value: +{
+  "confidence": {
+    "type": "string"
+  },
+  "coverage_ratio": {
+    "type": "number"
+  },
+  "expected_days": {
+    "type": "integer"
+  },
+  "freshness_days": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null
+  },
+  "gaps": {
+    "items": {
+      "properties": {
+        "days": {
+          "type": "integer"
+        },
+        "end": {
+          "type": "string"
+        },
+        "start": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "start",
+        "end",
+        "days"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "measurement_count": {
+    "type": "integer"
+  },
+  "missing_days": {
+    "type": "integer"
+  },
+  "observed_days": {
+    "type": "integer"
+  },
+  "observed_end": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null
+  },
+  "observed_start": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null
+  },
+  "recent_gap_days": {
+    "type": "integer"
+  },
+  "requested_end": {
+    "type": "string"
+  },
+  "requested_start": {
+    "type": "string"
+  }
+}

addedOutput schema / properties / evidence_a / required

Added value: +[
+  "requested_start",
+  "requested_end",
+  "expected_days",
+  "observed_days",
+  "coverage_ratio",
+  "missing_days",
+  "measurement_count",
+  "gaps",
+  "recent_gap_days",
+  "confidence"
+]

addedOutput schema / properties / evidence_a / type
```
Added value: +"object"
```

removedOutput schema / properties / evidence_b / anyOf

Removed value: -[
-  {
-    "description": "Coverage/quality of the data a single-metric analytical result is\nbased on. See evidence.build_evidence for how each field is computed.",
-    "properties": {
-      "confidence": {
-        "type": "string"
-      },
-      "coverage_ratio": {
-        "type": "number"
-      },
-      "expected_days": {
-        "type": "integer"
-      },
-      "freshness_days": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "gaps": {
-        "items": {
-          "properties": {
-            "days": {
-              "type": "integer"
-            },
-            "end": {
-              "type": "string"
-            },
-            "start": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "start",
-            "end",
-            "days"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "measurement_count": {
-        "type": "integer"
-      },
-      "missing_days": {
-        "type": "integer"
-      },
-      "observed_days": {
-        "type": "integer"
-      },
-      "observed_end": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "observed_start": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "recent_gap_days": {
-        "type": "integer"
-      },
-      "requested_end": {
-        "type": "string"
-      },
-      "requested_start": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "requested_start",
-      "requested_end",
-      "expected_days",
-      "observed_days",
-      "coverage_ratio",
-      "missing_days",
-      "measurement_count",
-      "gaps",
-      "recent_gap_days",
-      "confidence"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / evidence_b / default
```
Removed value: -null
```
addedOutput schema / properties / evidence_b / deprecated
```
Added value: +true
```

addedOutput schema / properties / evidence_b / description

Added value: +"DEPRECATED: identical to claim.evidence_b. Use claim.decision, not a standalone confidence field."

addedOutput schema / properties / evidence_b / properties

Added value: +{
+  "confidence": {
+    "type": "string"
+  },
+  "coverage_ratio": {
+    "type": "number"
+  },
+  "expected_days": {
+    "type": "integer"
+  },
+  "freshness_days": {
+    "anyOf": [
+      {
+        "type": "integer"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null
+  },
+  "gaps": {
+    "items": {
+      "properties": {
+        "days": {
+          "type": "integer"
+        },
+        "end": {
+          "type": "string"
+        },
+        "start": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "start",
+        "end",
+        "days"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "measurement_count": {
+    "type": "integer"
+  },
+  "missing_days": {
+    "type": "integer"
+  },
+  "observed_days": {
+    "type": "integer"
+  },
+  "observed_end": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null
+  },
+  "observed_start": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null
+  },
+  "recent_gap_days": {
+    "type": "integer"
+  },
+  "requested_end": {
+    "type": "string"
+  },
+  "requested_start": {
+    "type": "string"
+  }
+}

addedOutput schema / properties / evidence_b / required

Added value: +[
+  "requested_start",
+  "requested_end",
+  "expected_days",
+  "observed_days",
+  "coverage_ratio",
+  "missing_days",
+  "measurement_count",
+  "gaps",
+  "recent_gap_days",
+  "confidence"
+]

addedOutput schema / properties / evidence_b / type
```
Added value: +"object"
```
addedOutput schema / properties / evidence_profile / deprecated
```
Added value: +true
```

changedOutput schema / properties / evidence_profile / description

Previous value: -"Per-dimension evidence quality behind this result (sample, temporal, missingness, ...). Dimensions without an evaluator yet are 'not_assessed' and cap the claim, never count as adequate."New value: +"DEPRECATED: identical to claim.profile. Use claim.decision instead."

removedOutput schema / properties / sample_confidence
```
Removed value: -{
-  "type": "string"
-}
```

changedOutput schema / required

Previous value: -[
-  "evidence_profile",
-  "claim_decision",
-  "metric_a",
-  "metric_b",
-  "lag_days",
-  "n",
-  "sample_confidence"
-]New value: +[
+  "metric_a",
+  "metric_b",
+  "lag_days",
+  "n",
+  "claim",
+  "evidence_a",
+  "evidence_b",
+  "evidence_profile",
+  "claim_decision"
+]

Changed11 schema fields changedv1.0.23Sep 24, 2026

removedOutput schema / properties / claim_decision / anyOf

Removed value: -[
-  {
-    "properties": {
-      "must_state": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "permitted_phrasing_class": {
-        "type": "string"
-      },
-      "template": {
-        "type": "string"
-      },
-      "tier": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "tier",
-      "permitted_phrasing_class",
-      "must_state",
-      "template"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / claim_decision / default
```
Removed value: -null
```

addedOutput schema / properties / claim_decision / properties

Added value: +{
+  "must_state": {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  "permitted_phrasing_class": {
+    "type": "string"
+  },
+  "template": {
+    "type": "string"
+  },
+  "tier": {
+    "type": "string"
+  }
+}

addedOutput schema / properties / claim_decision / required

Added value: +[
+  "tier",
+  "permitted_phrasing_class",
+  "must_state",
+  "template"
+]

addedOutput schema / properties / claim_decision / type
```
Added value: +"object"
```

removedOutput schema / properties / evidence_profile / anyOf

Removed value: -[
-  {
-    "properties": {
-      "analysis": {
-        "type": "string"
-      },
-      "dimensions": {
-        "items": {
-          "properties": {
-            "can_block": {
-              "default": true,
-              "type": "boolean"
-            },
-            "details": {
-              "additionalProperties": true,
-              "type": "object"
-            },
-            "dimension": {
-              "enum": [
-                "sample",
-                "temporal",
-                "robustness",
-                "missingness",
-                "practical",
-                "measurement_validity",
-                "provenance"
-              ],
-              "type": "string"
-            },
-            "reason_codes": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "status": {
-              "enum": [
-                "adequate",
-                "negligible",
-                "not_assessed",
-                "weak",
-                "concern",
-                "blocking"
-              ],
-              "type": "string"
-            }
-          },
-          "required": [
-            "dimension",
-            "status"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "effect": {
-        "additionalProperties": true,
-        "type": "object"
-      },
-      "metric": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "metric",
-      "analysis",
-      "dimensions"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / evidence_profile / default
```
Removed value: -null
```

addedOutput schema / properties / evidence_profile / properties

Added value: +{
+  "analysis": {
+    "type": "string"
+  },
+  "dimensions": {
+    "items": {
+      "properties": {
+        "can_block": {
+          "default": true,
+          "type": "boolean"
+        },
+        "details": {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        "dimension": {
+          "enum": [
+            "sample",
+            "temporal",
+            "robustness",
+            "missingness",
+            "practical",
+            "measurement_validity",
+            "provenance"
+          ],
+          "type": "string"
+        },
+        "reason_codes": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "status": {
+          "enum": [
+            "adequate",
+            "negligible",
+            "not_assessed",
+            "weak",
+            "concern",
+            "blocking"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "dimension",
+        "status"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "effect": {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  "metric": {
+    "type": "string"
+  }
+}

addedOutput schema / properties / evidence_profile / required

Added value: +[
+  "metric",
+  "analysis",
+  "dimensions"
+]

addedOutput schema / properties / evidence_profile / type
```
Added value: +"object"
```

changedOutput schema / required

Previous value: -[
-  "metric_a",
-  "metric_b",
-  "lag_days",
-  "n",
-  "sample_confidence"
-]New value: +[
+  "evidence_profile",
+  "claim_decision",
+  "metric_a",
+  "metric_b",
+  "lag_days",
+  "n",
+  "sample_confidence"
+]

Changed2 schema fields changedv1.0.20Sep 20, 2026

addedOutput schema / properties / claim_decision

Added value: +{
+  "anyOf": [
+    {
+      "properties": {
+        "must_state": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "permitted_phrasing_class": {
+          "type": "string"
+        },
+        "template": {
+          "type": "string"
+        },
+        "tier": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "tier",
+        "permitted_phrasing_class",
+        "must_state",
+        "template"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "How strongly this result may be stated. tier is insufficient, suggestive, detectable_not_meaningful or supported; every entry in must_state has to be mentioned when reporting it."
+}

addedOutput schema / properties / evidence_profile

Added value: +{
+  "anyOf": [
+    {
+      "properties": {
+        "analysis": {
+          "type": "string"
+        },
+        "dimensions": {
+          "items": {
+            "properties": {
+              "can_block": {
+                "default": true,
+                "type": "boolean"
+              },
+              "details": {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              "dimension": {
+                "enum": [
+                  "sample",
+                  "temporal",
+                  "robustness",
+                  "missingness",
+                  "practical",
+                  "measurement_validity",
+                  "provenance"
+                ],
+                "type": "string"
+              },
+              "reason_codes": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "status": {
+                "enum": [
+                  "adequate",
+                  "negligible",
+                  "not_assessed",
+                  "weak",
+                  "concern",
+                  "blocking"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "dimension",
+              "status"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "effect": {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        "metric": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "metric",
+        "analysis",
+        "dimensions"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Per-dimension evidence quality behind this result (sample, temporal, missingness, ...). Dimensions without an evaluator yet are 'not_assessed' and cap the claim, never count as adequate."
+}

Changed2 schema fields changedv1.0.19Sep 18, 2026

addedOutput schema / properties / sample_confidence
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / required

Previous value: -[
-  "metric_a",
-  "metric_b",
-  "lag_days",
-  "n"
-]New value: +[
+  "metric_a",
+  "metric_b",
+  "lag_days",
+  "n",
+  "sample_confidence"
+]

Changed2 schema fields changedSep 15, 2026

addedOutput schema / properties / evidence_a

Added value: +{
+  "anyOf": [
+    {
+      "description": "Coverage/quality of the data a single-metric analytical result is\nbased on. See evidence.build_evidence for how each field is computed.",
+      "properties": {
+        "confidence": {
+          "type": "string"
+        },
+        "coverage_ratio": {
+          "type": "number"
+        },
+        "expected_days": {
+          "type": "integer"
+        },
+        "freshness_days": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "gaps": {
+          "items": {
+            "properties": {
+              "days": {
+                "type": "integer"
+              },
+              "end": {
+                "type": "string"
+              },
+              "start": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "start",
+              "end",
+              "days"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "measurement_count": {
+          "type": "integer"
+        },
+        "missing_days": {
+          "type": "integer"
+        },
+        "observed_days": {
+          "type": "integer"
+        },
+        "observed_end": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "observed_start": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "recent_gap_days": {
+          "type": "integer"
+        },
+        "requested_end": {
+          "type": "string"
+        },
+        "requested_start": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "requested_start",
+        "requested_end",
+        "expected_days",
+        "observed_days",
+        "coverage_ratio",
+        "missing_days",
+        "measurement_count",
+        "gaps",
+        "recent_gap_days",
+        "confidence"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedOutput schema / properties / evidence_b

Added value: +{
+  "anyOf": [
+    {
+      "description": "Coverage/quality of the data a single-metric analytical result is\nbased on. See evidence.build_evidence for how each field is computed.",
+      "properties": {
+        "confidence": {
+          "type": "string"
+        },
+        "coverage_ratio": {
+          "type": "number"
+        },
+        "expected_days": {
+          "type": "integer"
+        },
+        "freshness_days": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "gaps": {
+          "items": {
+            "properties": {
+              "days": {
+                "type": "integer"
+              },
+              "end": {
+                "type": "string"
+              },
+              "start": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "start",
+              "end",
+              "days"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "measurement_count": {
+          "type": "integer"
+        },
+        "missing_days": {
+          "type": "integer"
+        },
+        "observed_days": {
+          "type": "integer"
+        },
+        "observed_end": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "observed_start": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "recent_gap_days": {
+          "type": "integer"
+        },
+        "requested_end": {
+          "type": "string"
+        },
+        "requested_start": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "requested_start",
+        "requested_end",
+        "expected_days",
+        "observed_days",
+        "coverage_ratio",
+        "missing_days",
+        "measurement_count",
+        "gaps",
+        "recent_gap_days",
+        "confidence"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

Addedv1.0.16Sep 15, 2026
Removedv1.0.15Sep 15, 2026
Addedv1.0.11Sep 13, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), and the description goes well beyond them: it discloses that gappy or thin samples cap the claim tier rather than r, that data_health must be reported when not VALID, and adds a privacy note about local SQLite data flowing into cloud models. That is exactly the context structured fields cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose and organized under clear Use/Do-not-use/Reading-the-result headers. It runs long and the no-causation warning is restated across three consecutive sentences, which costs some density.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the presence of an output schema, the description supplies the interpretive contract — read claim.decision before r, treat template as a frame, translate must_state codes rather than quoting them, surface limiting_factors and data_health. For a statistics tool whose numbers are easy to over-report, that is the missing piece an agent needs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 60% and the two required params (metric_a, metric_b) carry no schema description; the description never clarifies what form those metric identifiers take or whether they may be equal. It does reinforce the lag/date-join semantics ('joined by date', 'over the same window'), but mainly restates what lag_days and start/end_date already document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — Pearson correlation between two metrics over the same window, joined by date — and immediately scopes the scope of the claim ('association, not causation'). It is trivially distinguishable from aggregate_measurements, get_baseline, or explain_metric_change.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use list with example phrasings, plus three named do-not-use branches routing to get_baseline/calculate_metric_trend/detect_metric_anomalies, explain_metric_change, and compare_metric_periods. An agent can pick the correct sibling without opening any other schema.

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

Find correlation between two metrics

Instructions

Tool call template

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools