fix: surface source description in MCP tool description (#267) (#309)

* fix: surface source description in MCP tool description

The `description` field on TOML [[sources]] was parsed into SourceConfig
and exposed via the REST /api/sources endpoint, but never surfaced
through MCP tool metadata. AI clients using DBHub via MCP only saw the
hardcoded template "Execute SQL queries on the '<id>' <dbType> database"
regardless of how the user described the source, making it impossible
for models to route requests between multiple sources based on the
user's descriptions.

Prepend sourceConfig.description (when set) to both execute_sql and
search_objects generated tool descriptions so AI clients see the
source's purpose first while retaining all existing technical context
(readonly note, max_rows note, dbType, source id).

Custom tool descriptions (CustomToolConfig.description) are untouched
because custom tools already carry their own required description.

Fixes #267

* refactor: extract buildSourceDescriptionPrefix helper and normalize input

Addresses Copilot review feedback on PR #309:

- Extract prefix-building logic into a pure helper `buildSourceDescriptionPrefix`
  used by both `getExecuteSqlMetadata` and `getSearchObjectsMetadata` instead
  of inlining the same expression twice.
- Trim surrounding whitespace from the user-provided description so leading
  or trailing whitespace does not leak into the MCP tool description.
- Skip appending '.' when the description already ends with a sentence-ending
  character (one of '.', '!', '?') to avoid double punctuation such as
  "Prod DB.. Execute SQL...".

Adds 10 pure unit tests in src/utils/__tests__/tool-metadata.test.ts
covering undefined/empty/whitespace-only inputs, each sentence-ending
punctuation case, whitespace trimming, preservation of internal formatting,
and documenting that mid-sentence punctuation (':', ';', ')') is still
terminated with '. '.

* refactor: treat trailing ':' as terminator to avoid ':.' artifact

Addresses second-pass Copilot review on PR #309: descriptions ending
with a colon (e.g. "Details below:") produced the awkward artifact
"Details below:. Execute SQL..." under the previous regex.

A trailing colon naturally introduces what follows (the generic tool
template), so appending "." after it is both ugly and semantically
redundant. Extend the terminator regex to /[.!?:]$/ and update the
corresponding test case. ';' and ')' remain non-terminators because
they signal mid-sentence continuation rather than introduction.

---------

Co-authored-by: IslaLiu <C19087@csccss.com.tw>

Author: Isla-Liu

src/utils/__tests__/tool-metadata.integration.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import type { ConnectorManager } from "../../connectors/manager.js";
+import { setupManagerWithFixture, FIXTURES, loadFixtureConfig } from "../../__fixtures__/helpers.js";
+import { getExecuteSqlMetadata, getSearchObjectsMetadata } from "../tool-metadata.js";
+import { initializeToolRegistry } from "../../tools/registry.js";
+
+// Import SQLite connector to ensure it's registered
+import "../../connectors/sqlite/index.js";
+
+describe("tool-metadata description propagation", () => {
+  let manager: ConnectorManager;
+
+  beforeAll(async () => {
+    // readonly-maxrows fixture has three sources:
+    //   readonly_limited: description = "Read-only database for safe queries", readonly + max_rows
+    //   writable_limited: no description, writable + max_rows
+    //   writable_unlimited: no description, writable + no limits
+    manager = await setupManagerWithFixture(FIXTURES.READONLY_MAXROWS);
+    const { sources, tools } = loadFixtureConfig(FIXTURES.READONLY_MAXROWS);
+    initializeToolRegistry({ sources, tools: tools || [] });
+  }, 30000);
+
+  afterAll(async () => {
+    if (manager) {
+      await manager.disconnect();
+    }
+  });
+
+  describe("getExecuteSqlMetadata", () => {
+    it("prepends user description from source config when present", () => {
+      const metadata = getExecuteSqlMetadata("readonly_limited");
+
+      expect(metadata.description).toContain("Read-only database for safe queries");
+      // Original technical context must still be preserved
+      expect(metadata.description).toContain("readonly_limited");
+      expect(metadata.description).toContain("sqlite");
+      expect(metadata.description).toContain("[READ-ONLY MODE]");
+      // User description comes first, technical template follows
+      expect(metadata.description.indexOf("Read-only database for safe queries")).toBeLessThan(
+        metadata.description.indexOf("Execute SQL queries")
+      );
+    });
+
+    it("omits the prefix entirely when source has no description", () => {
+      const metadata = getExecuteSqlMetadata("writable_limited");
+
+      // No extra prefix — description starts with the template
+      expect(metadata.description.startsWith("Execute SQL queries")).toBe(true);
+      expect(metadata.description).toContain("writable_limited");
+      expect(metadata.description).toContain("sqlite");
+    });
+  });
+
+  describe("getSearchObjectsMetadata", () => {
+    it("prepends user description from source config when present", () => {
+      const metadata = getSearchObjectsMetadata("readonly_limited");
+
+      expect(metadata.description).toContain("Read-only database for safe queries");
+      expect(metadata.description).toContain("readonly_limited");
+      expect(metadata.description).toContain("sqlite");
+      expect(metadata.description.indexOf("Read-only database for safe queries")).toBeLessThan(
+        metadata.description.indexOf("Search and list database objects")
+      );
+    });
+
+    it("omits the prefix entirely when source has no description", () => {
+      const metadata = getSearchObjectsMetadata("writable_unlimited");
+
+      expect(metadata.description.startsWith("Search and list database objects")).toBe(true);
+      expect(metadata.description).toContain("writable_unlimited");
+      expect(metadata.description).toContain("sqlite");
+    });
+  });
+});

src/utils/__tests__/tool-metadata.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "vitest";
+import { buildSourceDescriptionPrefix } from "../tool-metadata.js";
+
+describe("buildSourceDescriptionPrefix", () => {
+  it("returns empty string when description is undefined", () => {
+    expect(buildSourceDescriptionPrefix(undefined)).toBe("");
+  });
+
+  it("returns empty string when description is empty", () => {
+    expect(buildSourceDescriptionPrefix("")).toBe("");
+  });
+
+  it("returns empty string when description is whitespace-only", () => {
+    expect(buildSourceDescriptionPrefix("   ")).toBe("");
+    expect(buildSourceDescriptionPrefix("\t\n")).toBe("");
+  });
+
+  it("appends '. ' when description has no sentence-ending punctuation", () => {
+    expect(buildSourceDescriptionPrefix("Prod DB")).toBe("Prod DB. ");
+  });
+
+  it("appends only a space when description already ends with a period", () => {
+    // Guards against the classic "Prod DB.. Execute SQL..." double-period bug.
+    expect(buildSourceDescriptionPrefix("Prod DB.")).toBe("Prod DB. ");
+  });
+
+  it("appends only a space when description ends with '!'", () => {
+    expect(buildSourceDescriptionPrefix("Production DB!")).toBe("Production DB! ");
+  });
+
+  it("appends only a space when description ends with '?'", () => {
+    expect(buildSourceDescriptionPrefix("Query me?")).toBe("Query me? ");
+  });
+
+  it("appends only a space when description ends with ':'", () => {
+    // A trailing colon naturally introduces what follows (the tool template),
+    // so adding '.' here would produce the artifact "Details below:. Execute..."
+    expect(buildSourceDescriptionPrefix("Details below:")).toBe("Details below: ");
+  });
+
+  it("trims surrounding whitespace before assessing punctuation", () => {
+    expect(buildSourceDescriptionPrefix("  Prod DB  ")).toBe("Prod DB. ");
+    expect(buildSourceDescriptionPrefix("  Prod DB.  ")).toBe("Prod DB. ");
+  });
+
+  it("preserves internal whitespace and punctuation", () => {
+    // Internal formatting (newlines, multiple words, mid-sentence punctuation)
+    // is the user's intent and must not be altered.
+    expect(buildSourceDescriptionPrefix("Line 1\nLine 2")).toBe("Line 1\nLine 2. ");
+    expect(buildSourceDescriptionPrefix("Line A, Line B")).toBe("Line A, Line B. ");
+  });
+
+  it("does not treat non-sentence-ending punctuation as terminators", () => {
+    // ')' and ';' are mid-sentence / structural punctuation; the helper
+    // should still append ". " to produce a complete sentence boundary.
+    // (':' is handled separately — see the colon-specific test above.)
+    expect(buildSourceDescriptionPrefix("(read-only)")).toBe("(read-only). ");
+    expect(buildSourceDescriptionPrefix("Clause 1; clause 2")).toBe("Clause 1; clause 2. ");
+  });
+});

src/utils/tool-metadata.ts

@@ -39,6 +39,33 @@ export interface ToolMetadata {
   annotations: ToolAnnotations;
 }
 
+/**
+ * Build a prefix string for prepending a source's user-provided `description`
+ * onto a generated tool description. Returns "" when no description is set
+ * (undefined, empty, or whitespace-only). Normalizes surrounding whitespace
+ * with `trim()` and skips adding a period when the description already ends
+ * with one of "." / "!" / "?" / ":" — the colon is included because a
+ * trailing colon naturally introduces what follows (the generic tool
+ * template) and appending "." after it would produce artifacts like
+ * "Details below:. Execute SQL...".
+ *
+ * Examples:
+ *   undefined            -> ""
+ *   "  "                 -> ""
+ *   "Prod DB"            -> "Prod DB. "
+ *   "Prod DB."           -> "Prod DB. "      (no double period)
+ *   "  Prod DB!  "       -> "Prod DB! "      (trimmed, no added period)
+ *   "Query me?"          -> "Query me? "
+ *   "Details below:"     -> "Details below: " (colon introduces what follows)
+ *   "Clause 1; clause 2" -> "Clause 1; clause 2. " (semicolon is mid-sentence)
+ *   "(read-only)"        -> "(read-only). "  (closing paren is mid-sentence)
+ */
+export function buildSourceDescriptionPrefix(description: string | undefined): string {
+  const trimmed = description?.trim() ?? "";
+  if (!trimmed) return "";
+  return /[.!?:]$/.test(trimmed) ? `${trimmed} ` : `${trimmed}. `;
+}
+
 /**
  * Convert a Zod schema object to simplified parameter list
  * @param schema - Zod schema object (e.g., { sql: z.string().describe("...") })
@@ -106,12 +133,15 @@ export function getExecuteSqlMetadata(sourceId: string): ToolMetadata {
     ? `Execute SQL (${dbType})`
     : `Execute SQL on ${sourceId} (${dbType})`;
 
-  // Determine description with more context
+  // Determine description with more context.
+  // Prepend the user-provided `description` from the source config (if set)
+  // so AI clients reading the MCP tool list see the source's purpose first.
+  const userDescPrefix = buildSourceDescriptionPrefix(sourceConfig.description);
   const readonlyNote = executeOptions.readonly ? " [READ-ONLY MODE]" : "";
   const maxRowsNote = executeOptions.maxRows ? ` (limited to ${executeOptions.maxRows} rows)` : "";
   const description = isSingleSource
-    ? `Execute SQL queries on the ${dbType} database${readonlyNote}${maxRowsNote}`
-    : `Execute SQL queries on the '${sourceId}' ${dbType} database${readonlyNote}${maxRowsNote}`;
+    ? `${userDescPrefix}Execute SQL queries on the ${dbType} database${readonlyNote}${maxRowsNote}`
+    : `${userDescPrefix}Execute SQL queries on the '${sourceId}' ${dbType} database${readonlyNote}${maxRowsNote}`;
 
   // Build annotations object with all standard MCP hints
   const isReadonly = executeOptions.readonly === true;
@@ -149,9 +179,12 @@ export function getSearchObjectsMetadata(sourceId: string): { name: string; desc
   const title = isSingleSource
     ? `Search Database Objects (${dbType})`
     : `Search Database Objects on ${sourceId} (${dbType})`;
+  // Prepend the user-provided `description` from the source config (if set)
+  // so AI clients reading the MCP tool list see the source's purpose first.
+  const userDescPrefix = buildSourceDescriptionPrefix(sourceConfig.description);
   const description = isSingleSource
-    ? `Search and list database objects (schemas, tables, columns, procedures, functions, indexes) on the ${dbType} database`
-    : `Search and list database objects (schemas, tables, columns, procedures, functions, indexes) on the '${sourceId}' ${dbType} database`;
+    ? `${userDescPrefix}Search and list database objects (schemas, tables, columns, procedures, functions, indexes) on the ${dbType} database`
+    : `${userDescPrefix}Search and list database objects (schemas, tables, columns, procedures, functions, indexes) on the '${sourceId}' ${dbType} database`;
 
   return {
     name: toolName,