gasp-standard-mcp 1.14.0 → 1.14.2

package/README.md

@@ -33,24 +33,24 @@ Restart your MCP client after adding the config.
 
 | Tool | Description |
 |------|-------------|
-| `lookup_metric` | Full metric details: department, signal type, definition, formula, benchmarks, entities, common mistakes, sources and page URL. Matches exactly (formula id, name with or without its abbreviation, abbreviation, graph label, alias or slug), prefers the full record over a cross-reference stub and suggests close names (misspellings included) when nothing matches. A name two departments define (Escalation Rate) lists each candidate with department, formula id and URL; qualify by department ("Support Escalation Rate") or pass the formula id. Falls back to glossary terms when no metric matches |
-| `lookup_definition` | Glossary term lookup (e.g. Signal Type, Sensitivity Tier, Access Scope, Metric Owner, CEL): full definition, section, canonical or reference link and page URL. Matches exactly and suggests close terms instead of guessing |
-| `list_metrics` | List all metrics, optionally filtered by exact department name (case-insensitive; an unknown name returns the department list) and/or signal type. The Core tier is the Core department |
-| `get_formula` | Canonical formula in the GASP formula grammar, with unit, O/M forms, variants, inputs with polarity, raw fields with the datasets they live in and the enum filters each form applies (CAC-O reads `cost_function in (gtm, implementation, onboarding)`, CAC-M `cost_function = gtm`). Metrics that cannot be computed carry the reason |
-| `get_relationships` | Upstream/downstream relationships for metrics, entities or concepts. 21 relationship types across signal, lifecycle, ownership, interaction and financial flow categories. Metric names resolve as in `lookup_metric`, ambiguity included. An entity also lists every metric whose formula reads its datasets (from `entityMappings`), with department and URL |
-| `get_data_requirements` | Data requirements for implementing a metric or a department: each field with its type and the dataset it is read from, the staged flag, grain, source, page URL and example SQL. The metric resolves exactly as in `lookup_metric`; `department` (exact name) lists a department or picks between metrics sharing a name. Optional `breakdown` names a breakdown the metric declares (`by_plan` on MRR) and returns that breakdown's requirement: the dimension among the fields and example SQL with one row per value; an unknown name lists the declared ones. Optional `dialect` (`postgres`, `snowflake`, `bigquery`, `databricks`) writes the example SQL for that warehouse |
-| `search` | Whole-word search across metrics (names, aliases, definitions, formulas, fields) and glossary definitions. Up to 10 results, one per metric or term, ranked name and alias above definition above formula and field, each with what matched and its gaspwiki.com URL. A query that matches nothing returns the closest names as "Did you mean" |
-| `generate_query` | Compile warehouse-specific SQL from the metric's canonical formula and an adapter mapping. One scalar subquery per aggregate, each reading the table mapped for its dataset, with `:period_start` and `:period_end` parameters. Unmapped fields stay as `{{field@dataset}}` placeholders. Optional `breakdown` names a breakdown the metric declares (`by_plan` on MRR) and returns one row per value of its field; an unknown name lists the declared ones. Optional `dialect` (`postgres`, `snowflake`, `bigquery`, `databricks`; `postgres` also covers Redshift) picks the SQL syntax for date arithmetic, casts and percentiles; without it the adapter's `warehouse` decides when it names one of them, else postgres. The output says which dialect it used. Matches the metric exactly and suggests close names instead of guessing |
-| `validate_adapter` | Validate a GASP adapter mapping file. Applies the bundled adapter JSON Schema (draft 2020-12, version 1.1) first and lists each violation with its JSON path, then reports unknown fields and datasets, fields mapped to a dataset that does not carry them, dataset table conflicts, enum fields mapped without a transform and covered metrics without an owner. Computes coverage per metric against the exact field and dataset pairs its compiled SQL reads (full, partial or none) and ranks the highest-value next pairs to map |
-| `infer_drivers` | Diagnose what could explain an observed metric movement: ranked upstream candidates with paths and per-step edge classifications |
-| `explain_path` | Enumerate up to 5 edge chains between two metrics, with classification (metric_signal / structural / lifecycle / behavioral / assignment / generative) per step |
-| `coverage_gap` | Audit a metric set: one-hop upstream and downstream metrics missing from it, plus graph metrics with no path to or from it. Entities and concepts are ignored |
+| `lookup_metric` | Full record for one metric: department, category, signal type, definition, formulas as written, the canonical formula with unit, forms, variants and breakdowns, benchmarks, validation rules, common mistakes, sources, aliases, the entities it measures, operating and market forms, the recommended sensitivity tier and access scope and the page URL. Matches exactly, ignoring case: formula id, graph node id, name with or without its abbreviation, abbreviation, graph label, alias or slug, with the full record preferred over a cross-reference stub. A name two departments define (Escalation Rate) lists each candidate with department, formula id and URL; prefix the department ("Support Escalation Rate") or pass the formula id. A glossary term returns its definition and a miss returns close names (misspellings included) |
+| `lookup_definition` | Glossary term lookup (e.g. Signal Type, Sensitivity Tier, Access Scope, Metric Owner, CEL): full definition, section, canonical or reference link, where it is used and page URL. Matches the term, its slug or either part of "Term (Abbreviation)" exactly; a metric name points to `lookup_metric` and a miss returns close terms |
+| `list_metrics` | Metric names grouped by department and category, optionally filtered by department (case-insensitive, spaces or hyphens; an unknown name returns close names and the department list) and signal type (`outcome`, `leading`, `efficiency`, `operational`, primary or secondary). The Core tier is the Core department |
+| `get_formula` | Canonical formula in the GASP formula grammar, with unit, O/M forms, named variants, breakdowns (field, bucket and total mode), notes, input metrics with role and polarity, the fields and datasets the formula and each form read and the enum filters each form applies (CAC-O reads `cost_function in (gtm, implementation, onboarding)`, CAC-M `cost_function = gtm`), then the formula as written in the standard. Metrics that cannot be computed carry the reason |
+| `get_relationships` | One node of the relationship graph (metric, entity or concept) with its direct edges: upstream, measured by, downstream and measures. 21 relationship types across signal, lifecycle, ownership, interaction and financial flow categories. Metric names resolve as in `lookup_metric`, ambiguity included; a metric outside the graph says so. An entity also lists every metric whose formula reads its datasets (from `entityMappings`), with department and URL |
+| `get_data_requirements` | Data requirements for one metric, a department or every metric with a formula: per metric, each field and dataset pair with its type, the staged flag, source, grain, frequency, page URL and example SQL. The metric resolves exactly as in `lookup_metric`; `department` lists a department or picks between metrics sharing a name. Optional `breakdown` names a breakdown the metric declares (`by_plan` on MRR) and returns that breakdown's requirement: the dimension among the fields and example SQL with one row per value; an unknown name lists the declared ones. Optional `dialect` (`postgres` by default and for Redshift, `snowflake`, `bigquery`, `databricks`) writes the example SQL for that warehouse |
+| `search` | Whole-word phrase search across metrics (names, aliases, definitions, formulas, fields, categories, departments) and glossary terms (terms, definitions, sections); the last word may take a plural or verb ending. Up to 10 results, one per metric or term, ranked name, alias and term first, then words within them, then definitions, then formulas and fields, each with what matched and its gaspwiki.com URL. A query that matches nothing returns up to 6 close names as "Did you mean" |
+| `generate_query` | Compile warehouse SQL from the metric's canonical formula and an adapter. One scalar subquery per aggregate, each reading the table mapped for its dataset, with `:period_start` and `:period_end` date parameters (both inclusive). Unmapped pairs stay as `{{field@dataset}}` placeholders and are listed with any dataset lacking a table and any mapping conflict. Optional `breakdown` names a breakdown the metric declares (`by_plan` on MRR) and returns one row per value; an unknown name lists the declared ones. Optional `dialect` (`postgres`, `snowflake`, `bigquery`, `databricks`; `postgres` also covers Redshift) picks the SQL syntax for date arithmetic, casts and percentiles; without it the adapter's `warehouse` decides when it names one of them, else postgres. The output says which dialect it used |
+| `validate_adapter` | Validate a GASP adapter. Applies the bundled adapter JSON Schema (draft 2020-12, versions 1.0 and 1.1) first and lists each violation with its JSON path, then reports unknown fields and datasets, fields mapped to a dataset that does not carry them, bare column names on fields that live on several datasets, dataset table conflicts, enum fields mapped without a transform, covered metrics without an owner and owners naming unknown metrics. Scores every metric with a formula against the exact field and dataset pairs its compiled SQL reads (full, partial with the missing pairs or none) and ranks up to 15 unmapped pairs by how many partially covered metrics need them |
+| `infer_drivers` | Diagnose what could explain an observed metric movement: up to 25 upstream candidates ranked by attenuation score, each with its implied direction and path. Direction flips across `reduces` edges and negative-polarity inputs; a baseline input (MRR read at period start by NRR) is listed but not walked through. Metric nodes only; `maxDepth` 1 to 8 (default 6) |
+| `explain_path` | Up to 5 forward edge chains from one graph node to another, shortest first, with edge type, classification (metric_signal / structural / lifecycle / behavioral / assignment / generative), attenuation and direction flips per step and the target's end direction per path. A baseline edge can only start a path |
+| `coverage_gap` | Audit a metric set: metrics with a direct edge into or out of it that it leaves out, plus graph metrics with no path to or from it. Inputs that are ambiguous, outside the graph or not metrics are listed as unresolved with the reason |
 
 The traversal tools (`infer_drivers`, `explain_path`, `coverage_gap`) return paths, edge classifications and attenuation scores. A score says how strongly the graph connects two metrics, never how far one will move. The tools chain: `infer_drivers` picks candidates, `explain_path` shows the chain behind one and `coverage_gap` checks whether you measure it. For "what if" simulation, use the [TWIN Modifier](https://gaspwiki.com/v1/twin-modifier).
 
 ## Data
 
-Version 1.14.0.
+Version 1.14.2.
 
 - 301 metrics across 13 departments
 - 93 glossary definitions (80 SaaS domain + 13 GASP framework)

package/build/derive.js

@@ -182,7 +182,7 @@ export function computeDerived(data, current) {
     const temporal = JSON.parse(current.ontology);
     const sourcedFrom = ont.fields.flatMap((f) => (f.sources ?? []).map((s) => [f.id, s]));
     const belongs = ont.fields.flatMap((f) => (f.datasets ?? []).map((d) => [f.id, d]));
-    L.push("// ═══════════════════════════════════════════════════════════════", "// GASP Standard — SaaS Metric Knowledge Graph (Full Ontology)", "// Generated from the GASP Standard (https://gaspwiki.com) by `npm run derive`", "// ═══════════════════════════════════════════════════════════════", "//", `// Nodes: ${metricNodes.length} Metrics, ${ont.entities.length} Entities, ${ont.concepts.length} Concepts, ${Object.keys(ont.datasets).length} Datasets, ${ont.fields.length} Fields, ${ont.sourceCategories.length} Source Categories`, `// Edges: ${metricEdges.length} metric relationships, ${measures.length} MEASURES, ${entityEdges.length} entity/concept relationships, ${belongs.length} BELONGS_TO, ${sourcedFrom.length} SOURCED_FROM`, "//", "// Relationship types (metric signal): DRIVES, REDUCES, PREDICTS, COMPONENT_OF, MEASURES", "// Relationship types (entity): " + Object.values(ont.entityRelationships?.edgeTypeClassification ?? {}).flat().join(", "), "// Relationship types (data lineage): BELONGS_TO (Field → Dataset), SOURCED_FROM (Field → SourceCategory)", "//", "// Import: paste into Neo4j Browser or pipe to cypher-shell", "// ═══════════════════════════════════════════════════════════════", "", "// Clean slate (optional, uncomment to clear existing data)", "// MATCH (n) DETACH DELETE n;", "");
+    L.push("// ═══════════════════════════════════════════════════════════════", "// GASP Standard: SaaS Metric Knowledge Graph (Full Ontology)", "// Generated from the GASP Standard (https://gaspwiki.com) by `npm run derive`", "// ═══════════════════════════════════════════════════════════════", "//", `// Nodes: ${metricNodes.length} Metrics, ${ont.entities.length} Entities, ${ont.concepts.length} Concepts, ${Object.keys(ont.datasets).length} Datasets, ${ont.fields.length} Fields, ${ont.sourceCategories.length} Source Categories`, `// Edges: ${metricEdges.length} metric relationships, ${measures.length} MEASURES, ${entityEdges.length} entity/concept relationships, ${belongs.length} BELONGS_TO, ${sourcedFrom.length} SOURCED_FROM`, "//", "// Relationship types (metric signal): DRIVES, REDUCES, PREDICTS, COMPONENT_OF, MEASURES", "// Relationship types (entity): " + Object.values(ont.entityRelationships?.edgeTypeClassification ?? {}).flat().join(", "), "// Relationship types (data lineage): BELONGS_TO (Field → Dataset), SOURCED_FROM (Field → SourceCategory)", "//", "// Import: paste into Neo4j Browser or pipe to cypher-shell", "// ═══════════════════════════════════════════════════════════════", "", "// Clean slate (optional, uncomment to clear existing data)", "// MATCH (n) DETACH DELETE n;", "");
     L.push(`// ─── Metric Nodes (${metricNodes.length}) ─────────────────────────`);
     for (const n of metricNodes) {
         const m = byId.get(n.id) ?? data.metrics.find((x) => metricFormulaId(data, x) === n.id);

package/build/index.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { loadStandard, loadBundled, loadRemote, findDefinition, metricNodeId, getRelationships, resolveNodeResult, suggestNodes, search, metricFormulaId, isMetricStub } from "./loader.js";
 import { buildContext, inferDrivers, findPaths, coverageGap, noDriversMessage, } from "./traversal.js";
-import { SITE, metricUrl, definitionUrl, resolveDocLink } from "./urls.js";
+import { SITE, metricUrl, definitionUrl, nodeUrl, resolveDocLink } from "./urls.js";
 import { formatCanonicalFormula, resolveMetric, suggestMatches, formatAmbiguous, fillTemplate, validateAdapter, formatDataRequirement, breakdownTemplate, breakdownRequirement, chooseDialect } from "./tools.js";
 import { DIALECTS } from "./dialect.js";
 import { readFileSync } from "node:fs";
@@ -28,7 +28,7 @@ catch {
         }
     }
 }
-// Background version check — non-blocking, stderr only
+// Background version check: non-blocking, stderr only
 const VERSION_URL = "https://gaspwiki.com/api/standard-version.json";
 (async () => {
     try {
@@ -49,7 +49,7 @@ const VERSION_URL = "https://gaspwiki.com/api/standard-version.json";
         }
     }
     catch {
-        // Offline or gaspwiki.com unreachable — silently ignore
+        // Offline or gaspwiki.com unreachable: silently ignore
     }
 })();
 const PKG_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8")).version;
@@ -122,8 +122,14 @@ function formatDefinition(def) {
         parts.push(`**Used in:** ${def.usedIn.join(", ")}`);
     return parts.join("\n").replace(/\bEOM Standard\b/g, "GASP Standard");
 }
+/** The reply when a name given to a metric-only tool is a glossary term or matches nothing. */
+function notAMetric(name, resolved) {
+    if (resolved.kind === "definition")
+        return `"${name}" is a glossary term, not a metric: use lookup_definition (${definitionUrl(resolved.definition)}).`;
+    return `No metric is named "${name}".${suggestMatches(data, name)}`;
+}
 // --- Tool 1: lookup_metric ---
-server.tool("lookup_metric", "Look up a GASP Standard metric by exact name, abbreviation, alias or formula id. Returns definition, formula, benchmarks, time period, department and page URL. When a name belongs to several departments' metrics (e.g. 'Escalation Rate') it lists each with its department, formula id and URL; qualify by department ('Support Escalation Rate') or pass the formula id. Falls back to glossary terms (e.g. 'Signal Type', 'Metric Owner') when no metric matches; use lookup_definition to ask for a term directly.", { name: z.string().describe("Metric name, abbreviation or formula id (e.g. 'MRR', 'Net Revenue Retention', 'CAC Payback', 'support_escalation_rate')") }, async ({ name }) => {
+server.tool("lookup_metric", "The full record of one GASP Standard metric: department, category, signal type, page URL, definition, the formulas as written, the canonical GASP grammar formula (unit, forms, variants, breakdowns, fields and datasets), benchmarks, validation rules, common mistakes, sources, aliases, the entities it measures, operating and market forms, any adjusted variant and the recommended sensitivity tier and access scope. The name must match exactly, ignoring case: formula id, graph node id, full name, name without its abbreviation, abbreviation, graph label, alias or slug. A name several departments use (e.g. 'Escalation Rate') returns each candidate with department, formula id and URL; prefix the department ('Support Escalation Rate') or pass the formula id. A glossary term (e.g. 'Signal Type') returns its definition and a miss returns close names to retry with. Use get_formula for the formula alone and search when you do not know the name.", { name: z.string().describe("Exact metric name, abbreviation, alias, slug or formula id, case-insensitive (e.g. 'MRR', 'Net Revenue Retention', 'CAC Payback', 'support_escalation_rate'). Prefix the department to pick between metrics that share a name.") }, async ({ name }) => {
     const resolved = resolveMetric(data, name);
     if (resolved.kind === "ambiguous") {
         return { content: [{ type: "text", text: formatAmbiguous(data, name, resolved.candidates) }] };
@@ -254,15 +260,15 @@ server.tool("lookup_metric", "Look up a GASP Standard metric by exact name, abbr
     return { content: [{ type: "text", text }] };
 });
 // --- Tool 2: list_metrics ---
-server.tool("list_metrics", "List all GASP Standard metrics, optionally filtered by department and/or signal type. Returns metric names grouped by department and category. The Core tier is the 'Core' department. An unknown department returns the department list.", {
+server.tool("list_metrics", "List GASP Standard metric names grouped by department and category, with the total, optionally filtered by department, signal type or both. Names only: use lookup_metric or get_formula for a metric's details. A metric cross-referenced from another department is listed under both (NRR under Core and Customer Success). The Core tier is the 'Core' department. An unknown department returns close names and the department list.", {
     department: z
         .string()
         .optional()
-        .describe("Filter by exact department name (e.g. 'sales', 'customer success', 'core'). Case-insensitive. Omit to list all."),
+        .describe("Department name, case-insensitive, with spaces or hyphens (e.g. 'Sales', 'customer success', 'customer-success', 'Core'). Omit to list every department."),
     signalType: z
         .enum(["outcome", "leading", "efficiency", "operational"])
         .optional()
-        .describe("Filter by signal type. Returns metrics where primary or secondary type matches."),
+        .describe("outcome, leading, efficiency or operational. Matches a metric's primary or secondary signal type."),
 }, async ({ department, signalType }) => {
     let filtered = data.metrics;
     if (department) {
@@ -299,7 +305,9 @@ server.tool("list_metrics", "List all GASP Standard metrics, optionally filtered
         }
         dept.get(m.category).push(m.name);
     }
-    const parts = [`# GASP Standard Metrics (${filtered.length} total)\n`];
+    // A metric cross-referenced from another department is listed under both but counted once.
+    const distinct = new Set(filtered.map((m) => metricFormulaId(data, m))).size;
+    const parts = [`# GASP Standard Metrics (${distinct} total${distinct < filtered.length ? `, ${filtered.length} listings` : ""})\n`];
     for (const [dept, categories] of grouped) {
         parts.push(`## ${dept}`);
         for (const [cat, names] of categories) {
@@ -314,13 +322,13 @@ server.tool("list_metrics", "List all GASP Standard metrics, optionally filtered
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // --- Tool 3: get_formula ---
-server.tool("get_formula", "Get the canonical formula for a GASP Standard metric: the machine-readable GASP grammar formula with its unit, operating and market forms and named variants, the metrics, fields and datasets it and each form read, the enum filters each form applies (so forms reading the same fields show where they differ), plus the formula as written in the standard.", { metric: z.string().describe("Metric name, abbreviation or formula id (e.g. 'NRR', 'LTV', 'CAC Payback'). A name several departments use returns the candidates to choose from.") }, async ({ metric: name }) => {
+server.tool("get_formula", "The canonical formula of one GASP Standard metric in the GASP grammar, with its unit, operating (O) and market (M) forms, named variants, breakdowns (one row per value of a field or bucket; total() reads the whole population), notes, the metrics it reads with role and polarity, the fields and datasets the formula and each form read, the enum filters each form applies (so forms reading the same fields show where they differ) and the formula as written in the standard. A metric that cannot be computed as one formula gives the reason. Names resolve as in lookup_metric. Use get_data_requirements for field types and example SQL and generate_query for SQL against your own tables.", { metric: z.string().describe("Exact metric name, abbreviation, alias or formula id (e.g. 'NRR', 'LTV', 'CAC Payback', 'aging_buckets'). A name several departments use returns the candidates to choose from.") }, async ({ metric: name }) => {
     const resolved = resolveMetric(data, name);
     if (resolved.kind === "ambiguous") {
         return { content: [{ type: "text", text: formatAmbiguous(data, name, resolved.candidates) }] };
     }
     if (resolved.kind !== "metric") {
-        return { content: [{ type: "text", text: `No metric is named "${name}".${suggestMatches(data, name)}` }] };
+        return { content: [{ type: "text", text: notAMetric(name, resolved) }] };
     }
     const metric = resolved.metric;
     const parts = [`# ${metric.name}: Formula`, `**URL:** ${metricUrl(metric)}`, ""];
@@ -333,7 +341,7 @@ server.tool("get_formula", "Get the canonical formula for a GASP Standard metric
         parts.push("\n## As written in the standard");
         for (let i = 0; i < metric.formulas.length; i++) {
             if (metric.formulas.length > 1)
-                parts.push(`**Variant ${i + 1}:**`);
+                parts.push(`**Formula ${i + 1}:**`);
             parts.push("```\n" + metric.formulas[i] + "\n```");
         }
     }
@@ -366,7 +374,7 @@ function formatValidation(d, metric) {
     return bits.join("; ");
 }
 // --- Tool 4: get_relationships ---
-server.tool("get_relationships", "Get the upstream (what drives it) and downstream (what it drives) relationships for a metric, entity, or concept from the GASP relationship graph. Names resolve exactly as in lookup_metric (an ambiguous metric name lists the candidates). For an entity it also lists every metric whose formula reads the entity's datasets, with department and URL. Relationship types: metric signal (DRIVES, REDUCES, PREDICTS, COMPONENT_OF, MEASURES), entity lifecycle (CONVERTS_TO, PARENT_OF, BELONGS_TO), entity ownership (OWNS, GRANTS, PRICED_BY), entity interactions (MANAGES, SERVES, ENGAGES_VIA, SUBMITS, REPRESENTED_BY, SOURCES), entity financial flows (GENERATES, PRODUCES, CONTRIBUTES_TO, INCURS).", { metric: z.string().describe("Metric name or ID (e.g. 'arr', 'NRR'), entity (e.g. 'customer', 'subscription'), or concept (e.g. 'revenue', 'bookings')") }, async ({ metric: name }) => {
+server.tool("get_relationships", "One node of the GASP relationship graph (a metric, entity or concept) with its description, category and level and its direct edges, each neighbour with its edge type and description: upstream (edges into it), the metrics that measure it, downstream (edges out of it) and, for a metric, the entities it measures. For an entity it also lists every metric whose formula reads the entity's datasets, with department and URL. Edge types: drives, reduces, predicts, component and measures (metric signal); converts_to, parent_of and belongs_to (lifecycle); owns, grants and priced_by (ownership); manages, serves, engages_via, submits, represented_by and sources (interaction); generates, produces, contributes_to and incurs (financial flow). Metric names resolve as in lookup_metric; a metric outside the graph says so and a miss lists every node. Use infer_drivers or explain_path to walk more than one hop.", { metric: z.string().describe("Metric name, abbreviation or graph id (e.g. 'NRR', 'arr'), entity (e.g. 'customer', 'subscription') or concept (e.g. 'revenue', 'bookings'). Entity and concept names win over a metric with the same name.") }, async ({ metric: name }) => {
     const { node, upstream, downstream, measuredBy: readers, ambiguous, outsideGraph } = getRelationships(data, name);
     if (ambiguous)
         return { content: [{ type: "text", text: formatAmbiguous(data, name, ambiguous) }] };
@@ -384,47 +392,46 @@ server.tool("get_relationships", "Get the upstream (what drives it) and downstre
             ],
         };
     }
+    const kind = node.nodeType ?? "metric";
     const parts = [
-        `# ${node.label} — Relationships\n`,
+        `# ${node.label}: relationships\n`,
         `**Description:** ${node.description}`,
         `**Category:** ${node.category}`,
-        `**Level:** ${node.level}\n`,
+        `**Level:** ${node.level}`,
+        `**URL:** ${nodeUrl(node)}\n`,
     ];
+    const neighbour = (r) => `- **${r.node.label}** (${r.type}): ${r.node.description} ${nodeUrl(r.node)}`;
     const upDrivers = upstream.filter((r) => r.type !== "measures");
     const measuredBy = upstream.filter((r) => r.type === "measures");
     const downDriven = downstream.filter((r) => r.type !== "measures");
     const measures = downstream.filter((r) => r.type === "measures");
     if (upDrivers.length > 0) {
-        parts.push("## Upstream (what drives this metric)");
-        for (const r of upDrivers) {
-            parts.push(`- **${r.node.label}** (${r.type}) — ${r.node.description}`);
-        }
+        parts.push(kind === "metric" ? "## Upstream (what drives this metric)" : `## Upstream (edges into this ${kind})`);
+        for (const r of upDrivers)
+            parts.push(neighbour(r));
         parts.push("");
     }
     else {
-        parts.push("## Upstream\nNo upstream drivers (this is a top-level metric).\n");
+        parts.push(kind === "metric" ? "## Upstream\nNo upstream drivers (this is a top-level metric).\n" : `## Upstream\nNo edges lead into this ${kind}.\n`);
     }
     if (measuredBy.length > 0) {
         parts.push("## Measured by (metrics that measure this)");
-        for (const r of measuredBy) {
-            parts.push(`- **${r.node.label}** (${r.type}) — ${r.node.description}`);
-        }
+        for (const r of measuredBy)
+            parts.push(neighbour(r));
         parts.push("");
     }
     if (downDriven.length > 0) {
-        parts.push("## Downstream (what this metric drives)");
-        for (const r of downDriven) {
-            parts.push(`- **${r.node.label}** (${r.type}) — ${r.node.description}`);
-        }
+        parts.push(kind === "metric" ? "## Downstream (what this metric drives)" : `## Downstream (edges out of this ${kind})`);
+        for (const r of downDriven)
+            parts.push(neighbour(r));
     }
     else {
-        parts.push("## Downstream\nNo downstream metrics (this is a leaf metric).");
+        parts.push(kind === "metric" ? "## Downstream\nNo downstream metrics (this is a leaf metric)." : `## Downstream\nNo edges lead out of this ${kind}.`);
     }
     if (measures.length > 0) {
         parts.push("\n## Measures (what this metric measures)");
-        for (const r of measures) {
-            parts.push(`- **${r.node.label}** (${r.type}) — ${r.node.description}`);
-        }
+        for (const r of measures)
+            parts.push(neighbour(r));
     }
     if (readers.length > 0) {
         parts.push(`\n## Measured by, from the ontology (${readers.length} metrics reading this entity's datasets)`);
@@ -434,17 +441,17 @@ server.tool("get_relationships", "Get the upstream (what drives it) and downstre
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // --- Tool 5: get_data_requirements ---
-server.tool("get_data_requirements", "Get the data requirements for implementing a GASP Standard metric or department dashboard: each field the canonical formula reads with its type and the GASP dataset it is read from, whether the metric needs a staged dataset (cohort or prior-period comparison), reporting grain, source system, page URL and example SQL. The metric resolves exactly as in lookup_metric (name, abbreviation, alias or formula id); a name several departments use lists the candidates unless department picks one. Department is an exact name, case-insensitive. Pass breakdown with the name of a breakdown the metric declares (get_formula lists them, e.g. 'by_plan' on MRR) to get that breakdown's requirement: its fields include the dimension and the example SQL returns one row per value. Pass dialect (postgres, snowflake, bigquery, databricks; postgres also covers Redshift) to get the example SQL in that warehouse's syntax.", {
+server.tool("get_data_requirements", "What a warehouse needs to compute GASP Standard metrics: per metric, a row for each field and dataset pair the canonical formula reads with its type, whether it is staged (a cohort or prior-period comparison), source system, grain, frequency, page URL and example SQL compiled from the formula. Pass metric for one metric (resolved as in lookup_metric), department for every metric in it, both to pick between metrics that share a name and neither for every metric with a formula. breakdown names a breakdown the metric declares (get_formula lists them, e.g. 'by_plan' on MRR): the fields then include the dimension and the SQL returns one row per value. dialect (postgres, snowflake, bigquery or databricks; postgres is the default and also covers Redshift) sets the example SQL's syntax. A metric with no formula gives the reason. Use generate_query to fill the SQL from your adapter.", {
     metric: z
         .string()
         .optional()
-        .describe("Metric name, abbreviation or formula id (e.g. 'ARR', 'Pipeline Coverage Ratio', 'CSAT')"),
+        .describe("Exact metric name, abbreviation, alias or formula id (e.g. 'ARR', 'Pipeline Coverage Ratio', 'CSAT')"),
     department: z
         .string()
         .optional()
-        .describe("Exact department name (e.g. 'Sales', 'Engineering', 'Customer Success'). Alone it lists the department's requirements; with metric it picks between metrics that share a name."),
-    breakdown: z.string().optional().describe("Name of a named breakdown the metric declares (e.g. 'by_plan' on MRR); needs metric. The requirement then covers the breakdown's query, one row per value."),
-    dialect: z.enum(DIALECTS).optional().describe("SQL dialect of the example SQL: postgres (default, also Redshift), snowflake, bigquery or databricks; needs metric."),
+        .describe("Department name, case-insensitive (e.g. 'Sales', 'Engineering', 'customer success'). Alone it returns every requirement in the department; with metric it picks between metrics that share a name."),
+    breakdown: z.string().optional().describe("Name of a breakdown the metric declares (e.g. 'by_plan' or 'by_segment' on MRR); needs metric. The requirement then covers the breakdown's query, one row per value. An unknown name lists the declared ones."),
+    dialect: z.enum(DIALECTS).optional().describe("Dialect of the example SQL: postgres (default, also Redshift), snowflake, bigquery or databricks. Any but postgres needs metric."),
 }, async ({ metric, department, breakdown, dialect }) => {
     const all = data.dataRequirements || [];
     const text = (t) => ({ content: [{ type: "text", text: t }] });
@@ -466,7 +473,7 @@ server.tool("get_data_requirements", "Get the data requirements for implementing
         if (resolved.kind === "ambiguous")
             return text(formatAmbiguous(data, metric, resolved.candidates));
         if (resolved.kind !== "metric")
-            return text(`No metric is named "${metric}".${suggestMatches(data, metric)}`);
+            return text(notAMetric(metric, resolved));
         const id = metricFormulaId(data, resolved.metric);
         filtered = all.filter((dr) => dr.formulaId === id);
         if (filtered.length === 0) {
@@ -498,7 +505,7 @@ server.tool("get_data_requirements", "Get the data requirements for implementing
             pages.set(id, metricUrl(m));
     }
     const parts = [
-        `# Data Requirements (${filtered.length} entries)\n`,
+        `# Data Requirements (${filtered.length} ${filtered.length === 1 ? "entry" : "entries"}${metric && dialect ? `, example SQL in ${dialect}` : ""})\n`,
     ];
     // Group by department
     const grouped = new Map();
@@ -515,14 +522,14 @@ server.tool("get_data_requirements", "Get the data requirements for implementing
     return text(parts.join("\n"));
 });
 // --- Tool 6: search ---
-server.tool("search", "Search across all GASP Standard metrics and glossary definitions by whole words. Returns up to 10 results, one per metric or term, each with what matched and its URL: name and alias hits rank above definition hits, which rank above formula and field hits. When nothing matches (e.g. a misspelling) it returns the closest names labelled 'Did you mean'.", { query: z.string().describe("Search query (e.g. 'churn', 'retention', 'pipeline coverage')") }, async ({ query: q }) => {
+server.tool("search", "Find GASP Standard metrics and glossary terms when you do not know the exact name. The query matches as a phrase of whole words, the last word allowing a plural or verb ending ('churn' finds 'churned'), against metric names, aliases, definitions, formulas, the fields each formula reads, categories and departments, plus glossary terms, definitions and sections. Returns up to 10 results, one per metric or term, each with its type, department, what matched, a snippet and its URL. Names, aliases and terms rank first, then words within them, then definitions, then formulas and fields. When nothing matches (e.g. a misspelling) it returns up to 6 close names labelled 'Did you mean'. Pass a result's name to lookup_metric or lookup_definition.", { query: z.string().describe("Words to find (e.g. 'churn', 'retention', 'pipeline coverage', 'opportunity_stage')") }, async ({ query: q }) => {
     const results = search(data, q, 10);
     if (results.length === 0) {
         return {
             content: [
                 {
                     type: "text",
-                    text: `No results found for "${q}".`,
+                    text: `No results found for "${q}". Try fewer or broader words, or list_metrics to browse by department.`,
                 },
             ],
         };
@@ -539,25 +546,25 @@ server.tool("search", "Search across all GASP Standard metrics and glossary defi
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // --- Tool 7: generate_query ---
-server.tool("generate_query", "Generate SQL for a GASP metric from your adapter. The query is compiled from the metric's canonical formula: one scalar subquery per aggregate, each on the warehouse table you mapped to that GASP dataset, with :period_start and :period_end parameters. Fields you have not mapped stay as {{field@dataset}} placeholders, where the tag names the GASP dataset the column must come from. Pass breakdown with the name of a breakdown the metric declares (get_formula lists them, e.g. 'by_plan' on MRR) to get one row per value of its field. The SQL dialect (postgres, snowflake, bigquery, databricks; postgres also covers Redshift) is the dialect argument, else the adapter's warehouse when it names one of them, else postgres; the output says which it used.", {
-    metric: z.string().describe("Metric name or abbreviation (e.g. 'NRR', 'CAC', 'Pipeline Value', 'ARR')"),
-    adapter: z.string().describe("Your GASP adapter JSON string (see validate_adapter)"),
-    breakdown: z.string().optional().describe("Name of a named breakdown the metric declares (e.g. 'by_plan' on MRR). The query returns one row per value of the breakdown's field."),
-    dialect: z.enum(DIALECTS).optional().describe("SQL dialect: postgres (also Redshift), snowflake, bigquery or databricks. Defaults to the adapter's warehouse when it names one of them, else postgres."),
+server.tool("generate_query", "SQL for one GASP Standard metric against your warehouse, compiled from its canonical formula and filled from your adapter: one scalar subquery per aggregate, each reading the table mapped to its GASP dataset, with :period_start and :period_end date parameters (both inclusive). Pairs you have not mapped stay as {{field@dataset}} placeholders, where the tag names the GASP dataset the column must come from; the output lists them with any dataset that has no table and any mapping conflict, plus the URL, dialect, datasets, grain and the mapping it used. breakdown names a breakdown the metric declares (get_formula lists them, e.g. 'by_plan' on MRR) and returns one row per value. The dialect (postgres, snowflake, bigquery or databricks; postgres also covers Redshift) is the dialect argument, else the adapter's warehouse when it names one of them, else postgres. Check the adapter with validate_adapter first.", {
+    metric: z.string().describe("Exact metric name, abbreviation, alias or formula id (e.g. 'NRR', 'CAC', 'Pipeline Value', 'ARR'), resolved as in lookup_metric"),
+    adapter: z.string().describe("Your GASP adapter as a JSON string (schema: https://gaspwiki.com/schemas/gasp-adapter-v1.json; check it with validate_adapter)"),
+    breakdown: z.string().optional().describe("Name of a breakdown the metric declares (e.g. 'by_plan' on MRR). The query returns one row per value of the breakdown's field or bucket. An unknown name lists the declared ones."),
+    dialect: z.enum(DIALECTS).optional().describe("SQL dialect: postgres (also Redshift), snowflake, bigquery or databricks. Omit to use the adapter's warehouse when it names one of them (postgresql and redshift read as postgres), else postgres."),
 }, async ({ metric: metricName, adapter: adapterJson, breakdown, dialect: requestedDialect }) => {
     const resolved = resolveMetric(data, metricName);
     if (resolved.kind === "ambiguous") {
         return { content: [{ type: "text", text: formatAmbiguous(data, metricName, resolved.candidates) }] };
     }
     if (resolved.kind !== "metric") {
-        return { content: [{ type: "text", text: `No metric is named "${metricName}".${suggestMatches(data, metricName)}` }] };
+        return { content: [{ type: "text", text: notAMetric(metricName, resolved) }] };
     }
     let adapter;
     try {
         adapter = JSON.parse(adapterJson);
     }
     catch {
-        return { content: [{ type: "text", text: "Invalid adapter JSON." }] };
+        return { content: [{ type: "text", text: "Invalid adapter JSON: pass the adapter as a JSON string." }] };
     }
     if (!Array.isArray(adapter?.mappings)) {
         return { content: [{ type: "text", text: 'Adapter must have a "mappings" array. Template: https://gaspwiki.com/downloads/gasp-adapter-template.json' }] };
@@ -591,10 +598,10 @@ server.tool("generate_query", "Generate SQL for a GASP metric from your adapter.
     if (r.missingFields.length)
         parts.push(`**Unmapped fields (left as placeholders):** \`${r.missingFields.join("\`, \`")}\``);
     if (r.missingTables.length)
-        parts.push(`**Datasets with no table:** ${r.missingTables.join(", ")}. Add them under \"datasets\" in the adapter or map a field from each.`);
+        parts.push(`**Datasets with no table:** ${r.missingTables.join(", ")}. Name a table for each under \"datasets\" in the adapter, or map one of its fields with a schema.table column reference.`);
     for (const c of r.conflicts)
         parts.push(`**Conflict:** ${c}`);
-    parts.push("", "Parameters: `:period_start` and `:period_end` are dates bounding the reporting period.", "", "```sql\n" + r.sql + "\n```");
+    parts.push("", "Parameters: `:period_start` and `:period_end` are the first and last dates of the reporting period, both inclusive.", "", "```sql\n" + r.sql + "\n```");
     if (r.mapped.length) {
         parts.push("\n**Field mapping used:**");
         for (const m of r.mapped)
@@ -603,7 +610,7 @@ server.tool("generate_query", "Generate SQL for a GASP metric from your adapter.
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // --- Tool 8: validate_adapter ---
-server.tool("validate_adapter", "Validate a GASP adapter against the standard. First applies the adapter JSON Schema (https://gaspwiki.com/schemas/gasp-adapter-v1.json, version 1.1) and lists each violation with its JSON path: missing version or mappings, unknown version values, keys the schema does not allow and values of the wrong type. Then, whether or not the schema passed, it reports gaspField values not in the ontology, unknown datasets, fields mapped to a dataset that does not carry them, bare column names on fields that live on several datasets, datasets whose fields point at different tables, scores every metric against the field and dataset pairs its canonical formula reads (fully covered, partially covered, not covered), lists enum fields mapped without a transform, covered metrics with no declared owner and owners naming unknown metrics, and ranks the next pairs to map. Coverage needs a mappings array; without one only the schema result is returned.", { adapter: z.string().describe("The adapter JSON as a string. Template: https://gaspwiki.com/downloads/gasp-adapter-template.json") }, async ({ adapter: adapterJson }) => {
+server.tool("validate_adapter", "Check a GASP adapter against the standard and score its coverage. It first applies the adapter JSON Schema (https://gaspwiki.com/schemas/gasp-adapter-v1.json, versions 1.0 and 1.1) and lists each violation with its JSON path: missing version or mappings, unknown version values, keys the schema does not allow and values of the wrong type. Then, whether or not the schema passed, it reports gaspField values not in the ontology, unknown datasets, fields mapped to a dataset that does not carry them, bare column names on fields that live on several datasets, datasets whose fields point at different tables and pairs mapped twice. It counts the field and dataset pairs mapped and the datasets with a table, scores every metric with a formula against the pairs its compiled SQL reads (fully covered, partially covered with the missing pairs, not covered), lists enum fields mapped without a transform, covered metrics with no declared owner and owners naming unknown metrics. It also ranks up to 15 unmapped pairs by how many partially covered metrics need them. Without a mappings array only the schema result is returned. Run it before generate_query.", { adapter: z.string().describe("The adapter JSON as a string. Template: https://gaspwiki.com/downloads/gasp-adapter-template.json") }, async ({ adapter: adapterJson }) => {
     let adapter;
     try {
         adapter = JSON.parse(adapterJson);
@@ -615,10 +622,10 @@ server.tool("validate_adapter", "Validate a GASP adapter against the standard. F
     return { content: [{ type: "text", text }] };
 });
 // --- Tool 9: infer_drivers ---
-server.tool("infer_drivers", "Diagnose what could explain an observed metric movement. Walks the GASP relationship graph in reverse and ranks upstream metrics whose movement (in the inferred direction) is consistent with the observation. Returns ranked candidates with full path and per-step edge classifications. Structural reasoning, not numeric forecasting — scores are attenuation products, not magnitude estimates. Compose with explain_path to scrutinise a chain or coverage_gap to check whether a candidate is being measured. For counterfactual 'what if' simulation, use the TWIN Modifier at https://gaspwiki.com/v1/twin-modifier instead.", {
-    metric: z.string().describe("Metric name, abbreviation, or graph id (e.g. 'ARR', 'NRR', 'arr')"),
-    direction: z.enum(["up", "down"]).describe("Observed direction of movement"),
-    maxDepth: z.number().int().min(1).max(8).optional().describe("Maximum traversal depth (default 6)"),
+server.tool("infer_drivers", "Rank the upstream metrics that could explain an observed movement in a metric. Walks the GASP relationship graph backwards from the metric up to maxDepth edges and returns up to 25 candidates, each with the direction it would have moved, a score and its path to the metric. Direction flips across a reduces edge and across an input with negative polarity (a denominator or subtracted term), marked ↓ in the path. A baseline input (read at period start, as NRR reads MRR) is listed as a candidate but not walked through, since its own drivers cannot move the metric within the period. Scores are products of edge attenuations: they rank structural links and say nothing about magnitude. Works on metric nodes only. Follow up with explain_path for the chain behind a candidate or coverage_gap to check you track it; for 'what if' simulation use the TWIN Modifier at https://gaspwiki.com/v1/twin-modifier.", {
+    metric: z.string().describe("Metric name, abbreviation or graph id (e.g. 'ARR', 'Net Revenue Retention', 'nrr'), resolved as in lookup_metric. It must be a metric in the relationship graph."),
+    direction: z.enum(["up", "down"]).describe("Observed movement of the metric: up or down"),
+    maxDepth: z.number().int().min(1).max(8).optional().describe("Maximum number of edges to walk back, 1 to 8 (default 6)"),
 }, async ({ metric: name, direction: dirStr, maxDepth }) => {
     const { node, text: missing } = resolveNode(name);
     if (!node) {
@@ -626,7 +633,7 @@ server.tool("infer_drivers", "Diagnose what could explain an observed metric mov
     }
     if (!traversalCtx.metricNodeIds.has(node.id)) {
         return {
-            content: [{ type: "text", text: `"${node.label}" is not a metric node — infer_drivers operates on metrics only. Try get_relationships for entity/concept nodes.` }],
+            content: [{ type: "text", text: `"${node.label}" is ${node.nodeType === "concept" ? "a concept" : "an entity"}, not a metric. infer_drivers works on metric nodes only; use get_relationships for an entity or concept.` }],
         };
     }
     const observedDirection = dirStr === "up" ? 1 : -1;
@@ -638,7 +645,7 @@ server.tool("infer_drivers", "Diagnose what could explain an observed metric mov
     }
     const arrow = (d) => (d === 1 ? "↑" : "↓");
     const parts = [
-        `# ${node.label} ${arrow(observedDirection)} — Candidate drivers (${candidates.length})\n`,
+        `# ${node.label} ${arrow(observedDirection)}: candidate drivers (${candidates.length})\n`,
         `_Structural reasoning, not numeric forecasting. Scores are attenuation products (0–1) along the chain; they rank candidates but do not estimate magnitudes._\n`,
         `| # | Driver | Implied direction | Score | Path |`,
         `|---|--------|------------------|-------|------|`,
@@ -653,10 +660,10 @@ server.tool("infer_drivers", "Diagnose what could explain an observed metric mov
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // --- Tool 10: explain_path ---
-server.tool("explain_path", "Explain how one metric reaches another by enumerating edge chains in the GASP relationship graph. Each step carries the canonical edge type and a classification bucket (metric_signal / structural / lifecycle / behavioral / assignment / generative). Returns up to 5 distinct paths sorted by length then attenuation. Empty if disconnected in the forward direction. Compose with infer_drivers to scrutinise a candidate chain.", {
-    from: z.string().describe("Source metric or node (name, abbreviation, or id)"),
-    to: z.string().describe("Target metric or node"),
-    maxDepth: z.number().int().min(1).max(8).optional().describe("Maximum chain length (default 6)"),
+server.tool("explain_path", "How a movement in one graph node reaches another: up to 5 chains of edges followed forward from `from` to `to`, shortest first, then by highest score. Each step gives the edge type, its classification (metric_signal, structural, lifecycle, behavioral, assignment or generative), its attenuation and whether it inverts direction; each path gives its score and the direction the target moves when the source rises. A baseline edge (MRR into NRR) can only start a path. Names resolve as in get_relationships, so entities and concepts work too. No path means no forward chain within maxDepth: try the reverse. Use it on a candidate from infer_drivers.", {
+    from: z.string().describe("Starting node: a metric name, abbreviation or graph id, or an entity or concept (e.g. 'Health Score', 'customer')"),
+    to: z.string().describe("Target node, in the same forms as from (e.g. 'NRR')"),
+    maxDepth: z.number().int().min(1).max(8).optional().describe("Maximum chain length in edges, 1 to 8 (default 6)"),
 }, async ({ from, to, maxDepth }) => {
     const fromHit = resolveNode(from);
     const toHit = resolveNode(to);
@@ -670,31 +677,32 @@ server.tool("explain_path", "Explain how one metric reaches another by enumerati
         return {
             content: [{
                     type: "text",
-                    text: `# ${fromNode.label} → ${toNode.label}\n\nNo forward path found within depth ${maxDepth ?? 6}. They may be disconnected in this direction (try the reverse, or use coverage_gap to inspect connectivity).`,
+                    text: `# ${fromNode.label} → ${toNode.label}\n\nNo forward path found within depth ${maxDepth ?? 6}. They may be connected only in the other direction (swap from and to) or the chain may be longer than maxDepth.`,
                 }],
         };
     }
     const parts = [
-        `# ${fromNode.label} → ${toNode.label} — ${paths.length} path${paths.length === 1 ? "" : "s"}\n`,
+        `# ${fromNode.label} → ${toNode.label}: ${paths.length} path${paths.length === 1 ? "" : "s"}\n`,
+        `_End direction: how ${toNode.label} moves when ${fromNode.label} rises along that path. Scores are products of edge attenuations and say nothing about magnitude._\n`,
     ];
     for (let i = 0; i < paths.length; i++) {
         const p = paths[i];
-        parts.push(`## Path ${i + 1} — ${p.path.length} step${p.path.length === 1 ? "" : "s"}, score ${p.score.toFixed(3)}, end direction ${p.direction === 1 ? "↑" : "↓"}`);
+        parts.push(`## Path ${i + 1}: ${p.path.length} step${p.path.length === 1 ? "" : "s"}, score ${p.score.toFixed(3)}, end direction ${p.direction === 1 ? "↑" : "↓"}`);
         parts.push(`Classifications: ${renderClassifications(p.path)}\n`);
         for (let j = 0; j < p.path.length; j++) {
             const s = p.path[j];
             const flip = s.directionFlip ? " (↓ inverts direction)" : "";
             const fromLabel = traversalCtx.nodeById.get(s.from)?.label ?? s.from;
             const toLabel = traversalCtx.nodeById.get(s.to)?.label ?? s.to;
-            parts.push(`${j + 1}. **${fromLabel}** → **${toLabel}** — \`${s.edgeType}\` (${s.classification}, attenuation ${s.attenuation.toFixed(2)})${flip}`);
+            parts.push(`${j + 1}. **${fromLabel}** → **${toLabel}**: \`${s.edgeType}\` (${s.classification}, attenuation ${s.attenuation.toFixed(2)})${flip}`);
         }
         parts.push("");
     }
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // --- Tool 11: coverage_gap ---
-server.tool("coverage_gap", "Audit a metric set against the GASP relationship graph. Returns three groups: upstream_missing (one-hop drivers not in the set), downstream_missing (one-hop downstream metrics not in the set), and disconnected (in-graph metrics with no path of any length to/from the set). Operates on metric nodes only — entities and concepts are ignored. Use to identify gaps before instrumenting a dashboard, then compose with infer_drivers or explain_path to investigate specific candidates.", {
-    metrics: z.array(z.string()).min(1).describe("Metric names, abbreviations, or graph ids (e.g. ['ARR', 'NRR', 'CAC'])"),
+server.tool("coverage_gap", "Audit a set of tracked metrics against the GASP relationship graph. Returns three lists: upstream missing (metrics with a direct edge into the set that the set leaves out), downstream missing (metrics with a direct edge from the set that it leaves out) and disconnected (graph metrics with no path of any length, in either direction and through any node, to the set; the first 25 shown). Names resolve as in lookup_metric; an input that is ambiguous, outside the graph, not a metric or unknown is listed as unresolved with the reason. Use it before instrumenting a dashboard, then infer_drivers or explain_path on the candidates.", {
+    metrics: z.array(z.string()).min(1).describe("The metrics you track, as names, abbreviations or graph ids (e.g. ['ARR', 'NRR', 'CAC'])"),
 }, async ({ metrics }) => {
     const resolved = [];
     const unresolved = [];
@@ -705,19 +713,22 @@ server.tool("coverage_gap", "Audit a metric set against the GASP relationship gr
         }
         else {
             const r = resolveNodeResult(data, m);
-            unresolved.push(r.kind === "ambiguous" ? `${m} (ambiguous: ${r.candidates.map((c) => `\`${metricFormulaId(data, c)}\``).join(" or ")})` : m);
+            unresolved.push(r.kind === "ambiguous" ? `${m} (ambiguous: ${r.candidates.map((c) => `\`${metricFormulaId(data, c)}\``).join(" or ")})`
+                : r.kind === "node" ? `${m} (${r.node.nodeType === "concept" ? "a concept" : "an entity"}, not a metric)`
+                    : r.metric ? `${m} (not in the relationship graph)`
+                        : `${m} (no match)`);
         }
     }
     if (resolved.length === 0) {
         return {
-            content: [{ type: "text", text: `No metric nodes resolved from input: ${metrics.join(", ")}. Try ids like 'arr', 'nrr', 'cac' or labels like 'NRR'.` }],
+            content: [{ type: "text", text: `No input resolved to a metric in the relationship graph: ${unresolved.join(", ")}. Pass graph ids ('arr', 'nrr', 'cac') or names ('NRR', 'Net Revenue Retention').` }],
         };
     }
     const result = coverageGap(new Set(resolved), traversalCtx);
     const labelOf = (id) => traversalCtx.nodeById.get(id)?.label ?? id;
     const formatList = (ids) => ids.length === 0 ? "_(none)_" : ids.map((id) => `- ${labelOf(id)} (\`${id}\`)`).join("\n");
     const parts = [
-        `# Coverage gap — ${resolved.length} metric${resolved.length === 1 ? "" : "s"}\n`,
+        `# Coverage gap: ${resolved.length} metric${resolved.length === 1 ? "" : "s"}\n`,
         `**Tracked:** ${resolved.map((id) => `${labelOf(id)} (\`${id}\`)`).join(", ")}`,
     ];
     if (unresolved.length > 0) {
@@ -725,15 +736,15 @@ server.tool("coverage_gap", "Audit a metric set against the GASP relationship gr
     }
     parts.push("");
     parts.push(`## Upstream missing (${result.upstreamMissing.length})`);
-    parts.push(`_Direct drivers of the tracked set that aren't tracked. Add to capture root-cause signal._\n`);
+    parts.push(`_Metrics with a direct edge into the tracked set that you do not track. Adding them shows what moves the set._\n`);
     parts.push(formatList(result.upstreamMissing));
     parts.push("");
     parts.push(`## Downstream missing (${result.downstreamMissing.length})`);
-    parts.push(`_Metrics directly fed by the tracked set, not tracked. Add to see what the inputs translate into._\n`);
+    parts.push(`_Metrics with a direct edge from the tracked set that you do not track. Adding them shows what the set moves._\n`);
     parts.push(formatList(result.downstreamMissing));
     parts.push("");
     parts.push(`## Disconnected (${result.disconnected.length})`);
-    parts.push(`_In-graph metrics with no path (any length, either direction) to the tracked set._\n`);
+    parts.push(`_Graph metrics with no path of any length, in either direction, to the tracked set._\n`);
     if (result.disconnected.length > 25) {
         parts.push(formatList(result.disconnected.slice(0, 25)));
         parts.push(`\n_…and ${result.disconnected.length - 25} more._`);
@@ -745,7 +756,7 @@ server.tool("coverage_gap", "Audit a metric set against the GASP relationship gr
 });
 // Start the server
 // --- Tool 12: lookup_definition ---
-server.tool("lookup_definition", "Look up a GASP Standard glossary term (e.g. 'Signal Type', 'Sensitivity Tier', 'Access Scope', 'Metric Owner', 'Logo Churn Rate', 'CEL'). Returns the full definition, its section, related links and page URL. Use lookup_metric for metrics.", { term: z.string().describe("Term name, abbreviation or slug (e.g. 'Signal Type', 'CEL', 'metric-owner')") }, async ({ term }) => {
+server.tool("lookup_definition", "Look up a GASP Standard glossary term (e.g. 'Signal Type', 'Sensitivity Tier', 'Access Scope', 'Metric Owner', 'CEL'): the full definition and body, its section, the canonical or reference link, where it is used and the page URL. The term must match exactly, ignoring case: the term, its slug or either part of 'Term (Abbreviation)', so 'CEL' finds 'CEL (Commercial Event Ledger)'. A metric name points you to lookup_metric and a miss returns close names. Some metrics also have a short glossary entry (Logo Churn Rate, Win Rate); lookup_metric gives their formula and benchmarks.", { term: z.string().describe("Exact term, abbreviation or slug, case-insensitive (e.g. 'Signal Type', 'CEL', 'metric-owner')") }, async ({ term }) => {
     const def = findDefinition(data, term);
     if (!def) {
         const r = resolveMetric(data, term);

package/build/loader.js

@@ -92,7 +92,7 @@ export function loadStandard() {
         taxonomy = JSON.parse(readFileSync(taxonomyPath, "utf-8"));
     }
     catch {
-        // taxonomy.json not yet created — default to operational
+        // taxonomy.json not yet created: default to operational
     }
     // Merge signal types into metrics
     for (const m of metrics) {
@@ -129,7 +129,7 @@ export function loadStandard() {
     }
     // Enrich cross-reference stubs with canonical content fields.
     //
-    // Some metrics intentionally appear in multiple department files — e.g. NRR
+    // Some metrics intentionally appear in multiple department files, e.g. NRR
     // is defined canonically in core.md and listed as a "See [Core](core.md#...)"
     // stub in customer-success.md. Per-department records are needed to drive
     // department-scoped routes (e.g. /v1/metrics/customer-success/...), but
@@ -174,7 +174,7 @@ export function loadStandard() {
             m.sources = [...canon.sources];
         if (!m.aliases?.length)
             m.aliases = [...canon.aliases];
-        // dualLens and dualLensNote are intentionally NOT enriched — they are a
+        // dualLens and dualLensNote are intentionally NOT enriched: they are a
         // Core-only construct (asserted by data-integrity tests). Consumers that
         // need dual-lens content should resolve via slug to the Core record.
     }
@@ -619,7 +619,9 @@ export function suggestNodes(data, name, limit = 6) {
     const byWord = data.nodes.filter((n) => n.id.includes(q) || n.label.toLowerCase().includes(q));
     const near = closest(q, data.nodes.map((n) => ({ item: n, names: [n.label, n.id] })), limit).map((c) => c.item);
     const hits = [...new Set([...byWord, ...near])].map((n) => `${n.label} (${n.id})`).slice(0, limit);
-    return hits.length ? ` Did you mean: ${hits.join("; ")}? Pass the exact name or id.` : "";
+    return hits.length
+        ? ` Did you mean: ${hits.join("; ")}? Pass the exact name or id.`
+        : " No node label or id is close to it. The graph holds the Core and department metrics, entities and concepts only; use search to find the metric and lookup_metric to see whether it is in the graph.";
 }
 /**
  * Every metric that reads an entity's datasets, from ontology entityMappings