simple-dynamsoft-mcp 7.7.5 → 7.7.6

package/README.md

@@ -295,15 +295,15 @@ mcpServers:
 
 The server exposes this minimal tool surface:
 
-- `get_index` -- compact product/version/sample index with selection guidance
-- `search` -- semantic search across docs and samples (also accepts exact sample IDs); returns `doc://` and `sample://` links
+- `get_index` -- compact product/version/sample index with selection guidance and known capability facts (OCR, VIN, ID documents)
+- `search` -- semantic search across docs and samples (also accepts exact sample IDs); returns `doc://` and `sample://` links plus the matched passage (up to ~1500 chars) of the top 3 results (`content: "none"` returns links and short snippets only). Without `edition`/`platform`, MRZ and MDS search their web edition, and a DBR query that names exactly one edition (for example "web app" or "Android") searches that edition and says so
 - `read_document` -- read the full text (title, public docs URL, body) of a `doc://` URI returned by `search`
 - `list_samples` -- browse available samples for a product/edition/platform
 - `resolve_version` -- resolve current version for a product/edition/platform
 - `get_quickstart` -- opinionated quickstart: picks a sample by scenario, returns code + install instructions
 - `get_sample_files` -- get full project files for a known sample (discovered via list_samples or search)
 
-Typical doc Q&A flow: `search` -> `read_document` with the exact `doc://` URI -> answer from the returned text and cite its public URL. Clients that support MCP resources can also fetch the same `doc://` / `sample://` URIs with `resources/read`.
+Typical doc Q&A flow: `search` -> answer from a matched passage when it covers the question, otherwise `read_document` with the exact `doc://` URI -> answer from the returned text and cite its public URL. Clients that support MCP resources can also fetch the same `doc://` / `sample://` URIs with `resources/read`.
 
 DBR searches also cover the shared Capture Vision API pages that the DBR docs link to (for example `CaptureVisionRouter.capture()` and `getSimplifiedSettings()`/`updateSettings()`); these hits keep their official `capture-vision/docs` URL and are labelled `shared Capture Vision API used by DBR` in search results. Doc URIs are path-based (`doc://dbr/web/web/<version>/user-guide/use-in-framework`) and change only when the docs move or the SDK version changes.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.7.5",
+  "version": "7.7.6",
   "description": "MCP server for Dynamsoft SDKs - Capture Vision, Barcode Reader (Mobile/Python/Web), Dynamic Web TWAIN, and Document Viewer. Provides documentation, code snippets, and API guidance.",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
   "scripts": {
     "start": "node src/index.js",
     "test": "npm run test:lite",
-    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/request-logging.test.js test/unit/request-log-file.test.js test/unit/rag-signature-manifest.test.js test/unit/startup-timing.test.js test/unit/http-startup-readiness.test.js test/unit/resource-index-startup.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/update-sdk-versions.test.js test/unit/version-policy.test.js test/unit/query-expansion.test.js test/unit/docs-loader-enrich.test.js test/unit/shared-docs.test.js test/unit/vector-cache.test.js test/unit/doc-slugs.test.js test/unit/incremental-embedding.test.js",
+    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/request-logging.test.js test/unit/request-log-file.test.js test/unit/rag-signature-manifest.test.js test/unit/startup-timing.test.js test/unit/http-startup-readiness.test.js test/unit/resource-index-startup.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/update-sdk-versions.test.js test/unit/version-policy.test.js test/unit/query-expansion.test.js test/unit/docs-loader-enrich.test.js test/unit/shared-docs.test.js test/unit/vector-cache.test.js test/unit/doc-slugs.test.js test/unit/incremental-embedding.test.js test/unit/search-scope.test.js",
     "test:lite": "npm run test:stdio && npm run test:http && npm run test:package",
     "test:lexical": "node --test test/integration/stdio.test.js test/integration/http.test.js",
     "test:gemini": "node scripts/run-gemini-tests.mjs",

package/scripts/eval-retrieval.mjs

@@ -30,19 +30,43 @@ if (cases.length === 0) {
   process.exit(1);
 }
 
-const { ensureResourceIndexReady } = await import("../src/server/resource-index.js");
+const { ensureResourceIndexReady, formatScopeLabel, getSampleIdFromUri } = await import("../src/server/resource-index.js");
 const { searchResources } = await import("../src/rag/index.js");
 const { runRetrievalEval } = await import("./lib/retrieval-eval.mjs");
 const { isResultInScope } = await import("./lib/scope-matcher.mjs");
+const { buildSearchResultsResponse, createHitDescriber, runScopedSearch, searchResponseText } = await import("../src/server/helpers/search-response.js");
+
+const describeHit = createHitDescriber({ formatScopeLabel, getSampleIdFromUri });
+// The text of the search tool's own response for these results (eval cases
+// pass already-normalized product filters).
+const renderResponse = (testCase, results, contentMode) => searchResponseText(buildSearchResultsResponse({
+  query: testCase.query,
+  product: testCase.filters?.product || "",
+  results,
+  contentMode,
+  describeHit,
+  getSampleIdFromUri
+}));
 
 ensureResourceIndexReady();
-const report = await runRetrievalEval({ searchResources, cases, k: golden.k || 5, isInScope: isResultInScope });
+// Search in the scope the tool would use (edition defaults read from the query).
+const scopedSearch = async (params) => (await runScopedSearch(searchResources, params)).results;
+const report = await runRetrievalEval({
+  searchResources: scopedSearch,
+  cases,
+  k: golden.k || 5,
+  isInScope: isResultInScope,
+  renderResponse
+});
 report.provider = provider;
 
 const fmt = (value) => (value === null || value === undefined ? "n/a" : value.toFixed(3));
 for (const item of report.cases) {
   const flag = item.gap ? "GAP " : item.requiredHit === false ? "MISS" : "ok  ";
-  console.log(`${flag} ${item.id.padEnd(34)} recall=${fmt(item.recall)} mrr=${fmt(item.mrr)} ndcg=${fmt(item.ndcg)} dup=${item.duplicates} off=${item.offScope} rn=${item.releaseNotes} ms=${item.latencyMs.toFixed(0)}`);
+  const answer = item.answerInPassages === null
+    ? ""
+    : ` answer: snippets=${item.answerInSnippets ? "y" : "n"} passages=${item.answerInPassages ? "y" : "n"}`;
+  console.log(`${flag} ${item.id.padEnd(34)} recall=${fmt(item.recall)} mrr=${fmt(item.mrr)} ndcg=${fmt(item.ndcg)} dup=${item.duplicates} off=${item.offScope} rn=${item.releaseNotes} ms=${item.latencyMs.toFixed(0)}${answer}`);
   if (args.show || item.requiredHit === false) {
     for (const hit of item.top) {
       console.log(`       ${hit.rank}. [g${hit.grade}] [${hit.product}] ${hit.title} :: ${hit.url || hit.uri}`);
@@ -55,6 +79,7 @@ const s = report.summary;
 console.log(`\nprovider=${provider} cases=${s.cases} (gap=${s.gapCases}) k=${report.k}`);
 console.log(`recall@${report.k}=${fmt(s.recallAtK)} mrr=${fmt(s.mrr)} ndcg@${report.k}=${fmt(s.ndcgAtK)} required_hit=${fmt(s.requiredHitRate)}`);
 console.log(`duplicate_rate=${fmt(s.duplicateRate)} off_scope_rate=${fmt(s.offScopeRate)} release_notes_rate=${fmt(s.releaseNotesRate)}`);
+console.log(`answer_in_text cases=${s.answerCases} snippets=${fmt(s.answerInSnippetsRate)} passages=${fmt(s.answerInPassagesRate)} | mean_chars snippets=${fmt(s.meanSnippetChars)} passages=${fmt(s.meanPassageChars)}`);
 const lat = s.latencyMs;
 console.log(`latency_ms first_query=${lat.firstQuery.toFixed(0)} first_pass p50=${lat.p50FirstPass.toFixed(0)} p95=${lat.p95FirstPass.toFixed(0)} | warm p50=${lat.p50Warm.toFixed(0)} p95=${lat.p95Warm.toFixed(0)}`);
 

package/scripts/lib/retrieval-eval.mjs

@@ -25,9 +25,12 @@ function percentile(values, p) {
 
 // `isInScope(result, filters)` (when given) applies the server's own
 // product/edition/platform matching so cross-platform leakage is counted too.
+// `expectedEdition` checks the edition the server should pick on its own
+// (cases that pass no edition filter), independently of the filters.
 function isOffScope(result, testCase, isInScope) {
   const product = testCase.filters?.product;
   if (product && result.product !== product) return true;
+  if (testCase.expectedEdition && result.edition !== testCase.expectedEdition) return true;
   if (isInScope && !isInScope(result, testCase.filters || {})) return true;
   const prefixes = testCase.allowedUrlPrefixes;
   if (Array.isArray(prefixes) && prefixes.length > 0 && result.url) {
@@ -40,7 +43,30 @@ function isReleaseNotes(result) {
   return /\/release-notes?\//i.test(String(result.url || ""));
 }
 
-function scoreCase(testCase, results, k, isInScope) {
+function normalizeForMatch(text) {
+  return String(text || "").toLowerCase().replace(/\s+/g, " ");
+}
+
+// What an agent reads from the search tool's actual response in each content
+// mode. `renderResponse(testCase, results, contentMode)` returns that text
+// (scripts/eval-retrieval.mjs builds it with the tool's own response builder).
+function emittedText(testCase, results, k, renderResponse) {
+  if (!renderResponse) return { snippet: "", passage: "" };
+  const top = results.slice(0, k);
+  return {
+    snippet: renderResponse(testCase, top, "none"),
+    passage: renderResponse(testCase, top, "passage")
+  };
+}
+
+// answerTerms: groups of alternatives; the answer counts as present when
+// every group has at least one alternative in the text (case-insensitive).
+function answerPresent(text, answerTerms) {
+  const haystack = normalizeForMatch(text);
+  return answerTerms.every((group) => group.some((term) => haystack.includes(normalizeForMatch(term))));
+}
+
+function scoreCase(testCase, results, k, isInScope, renderResponse) {
   const relevant = new Map(
     Object.entries(testCase.relevant || {}).map(([url, grade]) => [normalizeUrl(url), Number(grade) || 0])
   );
@@ -57,6 +83,8 @@ function scoreCase(testCase, results, k, isInScope) {
 
   const urls = top.map((result) => normalizeUrl(result.url || result.uri));
   const duplicates = urls.length - new Set(urls).size;
+  const hasAnswer = Array.isArray(testCase.answerTerms) && testCase.answerTerms.length > 0;
+  const emitted = emittedText(testCase, results, k, renderResponse);
 
   return {
     id: testCase.id,
@@ -70,6 +98,10 @@ function scoreCase(testCase, results, k, isInScope) {
     offScope: top.filter((result) => isOffScope(result, testCase, isInScope)).length,
     releaseNotes: top.filter(isReleaseNotes).length,
     returned: top.length,
+    answerInSnippets: hasAnswer ? answerPresent(emitted.snippet, testCase.answerTerms) : null,
+    answerInPassages: hasAnswer ? answerPresent(emitted.passage, testCase.answerTerms) : null,
+    snippetChars: emitted.snippet.length,
+    passageChars: emitted.passage.length,
     top: top.map((result, index) => ({
       rank: index + 1,
       grade: gains[index],
@@ -90,6 +122,7 @@ function mean(values) {
 function summarize(caseScores, firstPass, warmPass) {
   const totalReturned = caseScores.reduce((sum, item) => sum + item.returned, 0) || 1;
   const required = caseScores.filter((item) => item.requiredHit !== null);
+  const answered = caseScores.filter((item) => item.answerInPassages !== null);
   return {
     cases: caseScores.length,
     gapCases: caseScores.filter((item) => item.gap).length,
@@ -100,6 +133,11 @@ function summarize(caseScores, firstPass, warmPass) {
     duplicateRate: caseScores.reduce((sum, item) => sum + item.duplicates, 0) / totalReturned,
     offScopeRate: caseScores.reduce((sum, item) => sum + item.offScope, 0) / totalReturned,
     releaseNotesRate: caseScores.reduce((sum, item) => sum + item.releaseNotes, 0) / totalReturned,
+    answerCases: answered.length,
+    answerInSnippetsRate: answered.length ? answered.filter((item) => item.answerInSnippets).length / answered.length : null,
+    answerInPassagesRate: answered.length ? answered.filter((item) => item.answerInPassages).length / answered.length : null,
+    meanSnippetChars: mean(caseScores.map((item) => item.snippetChars)),
+    meanPassageChars: mean(caseScores.map((item) => item.passageChars)),
     // First pass pays index loading and per-scope index builds; the warm pass
     // repeats the same queries, so it reflects steady-state search cost.
     latencyMs: {
@@ -112,7 +150,7 @@ function summarize(caseScores, firstPass, warmPass) {
   };
 }
 
-async function runRetrievalEval({ searchResources, cases, k = 5, isInScope }) {
+async function runRetrievalEval({ searchResources, cases, k = 5, isInScope, renderResponse }) {
   const caseScores = [];
   const firstPass = [];
   const warmPass = [];
@@ -121,7 +159,7 @@ async function runRetrievalEval({ searchResources, cases, k = 5, isInScope }) {
     const results = await searchResources({ query: testCase.query, ...(testCase.filters || {}), limit: k, throwOnError: true });
     const latencyMs = performance.now() - startedAt;
     firstPass.push(latencyMs);
-    caseScores.push({ ...scoreCase(testCase, results, k, isInScope), latencyMs });
+    caseScores.push({ ...scoreCase(testCase, results, k, isInScope, renderResponse), latencyMs });
   }
   for (const testCase of cases) {
     const startedAt = performance.now();

package/src/rag/index.js

@@ -30,7 +30,7 @@ import {
   dotProduct,
   isRateLimitError,
   expandQueryTokens,
-  extractSnippet
+  buildMatchFields
 } from "./search-utils.js";
 import { createProviderOrchestrator } from "./providers.js";
 import { createVectorCacheHelpers } from "./vector-cache.js";
@@ -46,7 +46,7 @@ const searchUtils = {
   dotProduct,
   isRateLimitError,
   expandQueryTokens,
-  extractSnippet,
+  buildMatchFields,
   entryMatchesScope: (entry, filters) => entryMatchesScope(entry, filters, {
     editionMatches,
     platformMatches

package/src/rag/lexical-provider.js

@@ -1,5 +1,5 @@
 import Fuse from "fuse.js";
-import { chunkMarkdown, expandQueryTokens, extractSnippet } from "./search-utils.js";
+import { buildMatchFields, chunkMarkdown, expandQueryTokens } from "./search-utils.js";
 
 const DEFAULT_FUSE_OPTIONS = {
   keys: [
@@ -150,7 +150,8 @@ function scoreDocument(index, doc, terms) {
   }
   return {
     score: computeBm25Score(index.headerStats, doc, terms) + bestScore,
-    snippetText: best ? best.text : doc.fallbackSnippet
+    passageText: best ? best.text : "",
+    fallbackSnippet: doc.fallbackSnippet
   };
 }
 
@@ -204,11 +205,11 @@ function createLexicalProvider({
       // out-of-scope fuzzy match deflate every in-scope fuse contribution (issue #147).
       let maxFuse = 0;
 
-      const snippetTextByUri = new Map();
+      const matchByUri = new Map();
       for (const doc of bm25Index.documents) {
         if (!entryMatchesScope(doc.entry, filters)) continue;
-        const { score, snippetText } = scoreDocument(bm25Index, doc, terms);
-        snippetTextByUri.set(doc.entry.uri, snippetText);
+        const { score, passageText, fallbackSnippet } = scoreDocument(bm25Index, doc, terms);
+        matchByUri.set(doc.entry.uri, { passageText, fallbackSnippet });
         if (score > 0) {
           bm25ScoreByUri.set(doc.entry.uri, score);
           if (score > maxBm25) maxBm25 = score;
@@ -237,9 +238,11 @@ function createLexicalProvider({
 
       merged.sort(compareLexicalResults);
       const ranked = merged.map((item) => {
-        const scored = attachScore(item.entry, item.score);
-        const snippet = extractSnippet(snippetTextByUri.get(item.entry.uri) || "", terms);
-        return snippet ? { ...scored, matchedSnippet: snippet } : scored;
+        const match = matchByUri.get(item.entry.uri) || {};
+        return {
+          ...attachScore(item.entry, item.score),
+          ...buildMatchFields(match.passageText, terms, match.fallbackSnippet)
+        };
       });
       if (limit) return ranked.slice(0, limit);
       return ranked;

package/src/rag/providers.js

@@ -300,6 +300,9 @@ function createProviderOrchestrator({
           uri: item.uri,
           hash: createHash("sha256").update(`${model}\n${item.text}`).digest("hex").slice(0, 32)
         }));
+        // Passages stay in memory only (not in the cache file): they come from
+        // the current docs, parallel to indexedItems.
+        const passages = items.map((item) => item.passage || "");
         const checkpointHashes = new Set();
         const collect = () => (ragConfig.rebuild
           ? new Map()
@@ -338,7 +341,7 @@ function createProviderOrchestrator({
           vectorCache.clearVectorIndexCheckpoint(checkpointFile);
           vectorCache.pruneOtherCaches({ provider: name, model, keepFile: cacheFile });
           logRag(`cache hit provider=${name} file=${cacheFile} items=${indexedItems.length}`);
-          return { items: indexedItems, vectors };
+          return { items: indexedItems, vectors, passages };
         }
 
         if (name === "gemini" && embedder.resetMetrics) {
@@ -431,7 +434,8 @@ function createProviderOrchestrator({
         );
         return {
           items: payload.items,
-          vectors: payload.vectors
+          vectors: payload.vectors,
+          passages
         };
       })();
       return indexPromise;
@@ -462,7 +466,7 @@ function createProviderOrchestrator({
           if (!entry || !utils.entryMatchesScope(entry, filters)) continue;
           const existing = bestByUri.get(item.uri);
           if (!existing || score > existing.score) {
-            bestByUri.set(item.uri, { entry, score, chunkText: item.text });
+            bestByUri.set(item.uri, { entry, score, passage: index.passages[i] });
           }
         }
 
@@ -477,11 +481,10 @@ function createProviderOrchestrator({
         const kept = ordered.filter((item) => item.score >= relativeFloor);
 
         const snippetTerms = baseQuery.toLowerCase().split(/\s+/).filter(Boolean);
-        const results = kept.map((item) => {
-          const scored = utils.attachScore(item.entry, item.score);
-          const snippet = utils.extractSnippet ? utils.extractSnippet(item.chunkText || "", snippetTerms, 240) : "";
-          return snippet ? { ...scored, matchedSnippet: snippet } : scored;
-        });
+        const results = kept.map((item) => ({
+          ...utils.attachScore(item.entry, item.score),
+          ...utils.buildMatchFields(item.passage, snippetTerms)
+        }));
 
         if (limit) return results.slice(0, limit);
         return results;

package/src/rag/search-utils.js

@@ -184,11 +184,17 @@ function expandQueryTokens(tokens) {
   return [...out];
 }
 
+// Cap for matched passages returned by search: one chunk (RAG_CHUNK_SIZE 1200)
+// plus its heading path. The same cap applies to semantic and lexical results.
+const PASSAGE_MAX_CHARS = 1500;
+
 // A ~maxLen window around the first query term found in text — used to give the
 // agent a matched snippet in search results (issues #146/#149).
 function extractSnippet(text, terms, maxLen = 240) {
   const cleaned = normalizeText(text);
   if (!cleaned) return "";
+  // Text that fits is returned whole, so its heading and leading context stay.
+  if (cleaned.length <= maxLen) return cleaned;
   const lower = cleaned.toLowerCase();
   let hitAt = -1;
   for (const term of terms) {
@@ -202,6 +208,50 @@ function extractSnippet(text, terms, maxLen = 240) {
   return (start > 0 ? "…" : "") + snippet + (start + maxLen < cleaned.length ? "…" : "");
 }
 
+// Function words that match almost any passage; a passage must share a word
+// other than these with the query to count as matched.
+const PASSAGE_STOPWORDS = new Set(
+  "a an and are as at be by can do does for from how i if in into is it its me my of on or so the this that to use using via what when where which with without you your".split(" ")
+);
+
+// Each word is kept whole and, when camelCase, also split into its parts
+// ("SelectSource" -> "selectsource", "select", "source"), so API names match
+// plain query words and lowercased identifiers alike.
+function wordTokens(text) {
+  const tokens = [];
+  for (const word of String(text || "").split(/[^A-Za-z0-9]+/)) {
+    if (!word) continue;
+    tokens.push(word.toLowerCase());
+    const parts = word.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(" ");
+    if (parts.length > 1) tokens.push(...parts);
+  }
+  return tokens;
+}
+
+// True when the passage contains a query content word (compared by stem, with
+// the query's synonym expansion). Semantic scores include the page title,
+// summary, and tags, so the best chunk of a header-driven hit can be an
+// unrelated or near-empty section; such chunks are not shown as passages.
+function passageMatchesQuery(passage, terms) {
+  const queryWords = expandQueryTokens(wordTokens(terms.join(" ")).filter((word) => !PASSAGE_STOPWORDS.has(word)));
+  if (queryWords.length === 0) return false;
+  const wanted = new Set(queryWords.map(stemToken));
+  return wordTokens(passage).some((word) => wanted.has(stemToken(word)));
+}
+
+// Short snippet plus the full matched passage (capped) for one search hit.
+// Both come from the passage only when it contains a query content word;
+// otherwise the snippet comes from `fallbackSnippet` (e.g. the page summary)
+// or is omitted, so an unrelated section is never shown as evidence.
+function buildMatchFields(passage, terms, fallbackSnippet = "") {
+  const fields = {};
+  const matched = Boolean(passage) && passageMatchesQuery(passage, terms);
+  const snippet = extractSnippet(matched ? passage : fallbackSnippet, terms);
+  if (snippet) fields.matchedSnippet = snippet;
+  if (matched) fields.matchedPassage = extractSnippet(passage, terms, PASSAGE_MAX_CHARS);
+  return fields;
+}
+
 function buildEntryBaseText(entry) {
   const parts = [entry.title, entry.summary];
   if (Array.isArray(entry.tags) && entry.tags.length > 0) {
@@ -230,7 +280,10 @@ function buildEmbeddingItems(resourceIndex, ragConfig) {
         items.push({
           id: `${entry.id}#${index}`,
           uri: entry.uri,
-          text: truncateText(combined, ragConfig.maxTextChars)
+          text: truncateText(combined, ragConfig.maxTextChars),
+          // The chunk alone (heading path + body), without the page header that
+          // is embedded with it; search returns this as the matched passage.
+          passage: chunk
         });
       });
       continue;
@@ -308,6 +361,8 @@ export {
   expandQueryTokens,
   stemToken,
   extractSnippet,
+  buildMatchFields,
+  PASSAGE_MAX_CHARS,
   buildEmbeddingItems,
   buildIndexSignature,
   normalizeVector,

package/src/server/create-server.js

@@ -72,8 +72,8 @@ export function createMcpServerInstance({ pkgVersion, resourceIndexApi, ragApi }
       "This server answers questions about five public Dynamsoft offerings: DBR, DWT, DDV, MRZ, MDS.",
       "",
       "How to use it:",
-      "- Call get_index first to see valid product/edition/platform combinations before asking the user anything.",
-      "- To answer from documentation: call search, then call read_document with the exact doc:// uri it returned, and base the answer on that text, citing the public documentation URL it contains. Do not answer from search summaries alone or hand doc:// links to the user.",
+      "- Call get_index first to see valid product/edition/platform combinations before asking the user anything. Its productSelection.capabilities lists known facts (OCR, VIN, ID documents) that take precedence over inference; for other capabilities, search before saying something is not offered.",
+      "- To answer from documentation: call search. When a matched passage in the search response covers the question, answer from it and cite its Source URL. Otherwise call read_document with the exact doc:// uri it returned, base the answer on that text, and cite the public documentation URL it contains. Do not answer from search summaries alone or hand doc:// links to the user.",
       "- For sample:// results, call get_sample_files with resource_uri to get the complete sample project.",
       "- Only ask the user to disambiguate dimensions that actually vary for the chosen product. Do NOT ask about dimensions that don't apply.",
       "",

package/src/server/helpers/search-response.js

@@ -0,0 +1,136 @@
+import { formatScoreLabel, formatScoreNote } from "./server-helpers.js";
+import { resolveSearchScope } from "../normalizers.js";
+
+// Runs a search in the scope resolveSearchScope picks (see normalizers.js).
+// An edition read from the query never hides every result: with no results
+// it searches again across all editions. `filters` are already normalized.
+async function runScopedSearch(searchResources, { query, product, edition, platform, ...rest }) {
+  const scope = resolveSearchScope({ query, product, edition, platform });
+  const results = await searchResources({ query, product, edition: scope.edition, platform, ...rest });
+  if (!scope.inferredFrom) return { results, scopeNote: "" };
+  if (results.length === 0) {
+    return { results: await searchResources({ query, product, edition, platform, ...rest }), scopeNote: "" };
+  }
+  return {
+    results,
+    scopeNote: `Searched the ${product.toUpperCase()} ${scope.edition} edition because the query names it; pass edition (or platform) explicitly to search another edition.`
+  };
+}
+
+// Matched passages are inlined for the top doc results, so an agent can answer
+// from the relevant section without a read_document round trip. Each passage
+// is capped by PASSAGE_MAX_CHARS (src/rag/search-utils.js); full pages stay
+// behind read_document. Samples are excluded: their indexed text is generated
+// metadata (name, category, scenario tags), not content.
+const SEARCH_PASSAGE_COUNT = 3;
+
+function formatSearchPassages(results, count = SEARCH_PASSAGE_COUNT) {
+  const blocks = results
+    .slice(0, count)
+    .map((entry, index) => ({ entry, rank: index + 1 }))
+    .filter(({ entry }) => entry.type === "doc" && entry.matchedPassage)
+    .map(({ entry, rank }) => {
+      const source = entry.url ? `\nSource: ${entry.url}` : "";
+      return `[${rank}] ${entry.title} (${entry.uri})${source}\n${entry.matchedPassage}`;
+    });
+  if (blocks.length === 0) return "";
+  return [
+    `Matched passages from the top ${count} results (call read_document for the full page):`,
+    ...blocks
+  ].join("\n\n");
+}
+
+// A resource_link description that lets an agent choose WITHOUT a follow-up
+// read: type | scope | version | score - summary, then the matched snippet and
+// canonical URL when available (issue #146).
+function createHitDescriber({ formatScopeLabel, getSampleIdFromUri }) {
+  return function describeHit(entry) {
+    const versionLabel = entry.version ? `v${entry.version}` : "n/a";
+    const scopeLabel = formatScopeLabel(entry);
+    const sampleId = entry.type === "sample" ? getSampleIdFromUri(entry.uri) : "";
+    const sampleHint = sampleId ? ` | sample_id: ${sampleId}` : "";
+    const scoreLabel = formatScoreLabel(entry);
+    const sharedLabel = entry.type === "doc" && Array.isArray(entry.tags) && entry.tags.includes("shared")
+      ? ` | shared Capture Vision API used by DBR (DCV v${entry.sourceVersion || "n/a"})`
+      : "";
+    let desc = `${entry.type.toUpperCase()} | ${scopeLabel} | ${versionLabel}${sharedLabel}${scoreLabel} - ${entry.summary}${sampleHint}`;
+    if (entry.matchedSnippet) {
+      const snippet = String(entry.matchedSnippet).replace(/\s+/g, " ").slice(0, 220);
+      desc += ` — "${snippet}"`;
+    }
+    if (entry.type === "doc" && entry.url) {
+      desc += ` | ${entry.url}`;
+    }
+    return desc;
+  };
+}
+
+// The search tool's response for ranked results: lead text, one resource_link
+// per hit, matched passages (unless contentMode is "none"), plain URI list.
+// `product` is the normalized product filter (empty when none was given);
+// `scopeNote` explains a search scope the server chose (empty when none).
+function buildSearchResultsResponse({ query, product, scopeNote = "", results, contentMode, describeHit, getSampleIdFromUri }) {
+  const passages = contentMode === "none" ? "" : formatSearchPassages(results);
+  const linkGuidance = "call read_document with the exact uri of a doc:// result for the full page, or get_sample_files with resource_uri for a sample:// result.";
+  const readGuidance = passages
+    ? `Matched passages of the top results follow the links; when they do not cover the question, ${linkGuidance}`
+    : `To read a result, ${linkGuidance}`;
+  const found = `Found ${results.length} result(s) for "${query}".${scopeNote ? ` ${scopeNote}` : ""} ${readGuidance}`;
+  // Capture Vision / DCV is the umbrella framework, not a selectable public
+  // product; steer the agent to the right offering (issue #150).
+  const dcvUmbrella = /\b(capture[\s-]?vision|dcv)\b/i.test(query) && !product;
+  const leadText = dcvUmbrella
+    ? `"Capture Vision" (DCV) is Dynamsoft's umbrella framework — pick the public product for your task: DBR (barcodes), MRZ (passports/IDs), MDS (document capture), DWT (scanner hardware), DDV (document viewer). Results below span the closest matches.\n${found}`
+    : found;
+
+  const content = [{ type: "text", text: leadText }];
+  for (const entry of results) {
+    content.push({
+      type: "resource_link",
+      uri: entry.uri,
+      name: entry.title,
+      description: describeHit(entry),
+      mimeType: entry.mimeType,
+      annotations: {
+        audience: ["assistant"],
+        priority: 0.8
+      }
+    });
+  }
+  if (passages) {
+    content.push({ type: "text", text: passages });
+  }
+
+  const plainLines = results.map((entry, index) => {
+    const sampleId = entry.type === "sample" ? getSampleIdFromUri(entry.uri) : "";
+    const action = entry.type === "sample" ? "get_sample_files resource_uri" : "read_document uri";
+    const sampleNote = sampleId ? ` sample_id=${sampleId}` : "";
+    const scoreNote = formatScoreNote(entry);
+    return `- ${index + 1}. ${entry.uri}${sampleNote}${scoreNote} (${action})`;
+  });
+  content.push({
+    type: "text",
+    text: ["Plain URIs (copy/paste):", ...plainLines].join("\n")
+  });
+
+  return { content };
+}
+
+// Everything an agent reads from a search response: text items plus each
+// link's uri, name, and description.
+function searchResponseText(response) {
+  return response.content
+    .map((item) => (item.type === "resource_link"
+      ? [item.uri, item.name, item.description].filter(Boolean).join("\n")
+      : item.text || ""))
+    .join("\n\n");
+}
+
+export {
+  SEARCH_PASSAGE_COUNT,
+  formatSearchPassages,
+  createHitDescriber,
+  buildSearchResultsResponse,
+  searchResponseText,
+  runScopedSearch
+};

package/src/server/normalizers.js

@@ -402,6 +402,36 @@ function inferProductFromQuery(query) {
   return "";
 }
 
+// Edition hints for DBR searches, checked against the current query only.
+// React Native and Node.js (also written "node js", "node-js") are removed
+// before the web check so their "js"/"react" do not also count as web.
+const NON_WEB_JS = /react[\s-]?native|node[\s.-]?js/g;
+const QUERY_EDITION_PATTERNS = {
+  mobile: /\b(?:android|ios|iphone|ipad|swift|kotlin|flutter|maui|xamarin|react[\s-]?native|mobile)\b/,
+  server: /\b(?:python|java|cpp|csharp|dotnet|node[\s.-]?js|server|desktop)\b|(?<![a-z0-9])(?:c\+\+|c#|\.net)(?![a-z0-9])/,
+  web: /\b(?:web|browser|javascript|typescript|js|react|angular|vue|svelte|nuxt|next\.?js|html)\b/
+};
+
+// The edition a search runs in when the caller gave neither edition nor
+// platform. MRZ and MDS are served for web only, so they default to web.
+// For DBR, an edition is taken from the query only when it names exactly one
+// edition unambiguously ("web app", "Android"); otherwise all editions are
+// searched. `inferredFrom` is set when the query decided the edition, so the
+// response can say so.
+function resolveSearchScope({ query, product, edition, platform }) {
+  if (edition || platform) return { edition: edition || "", inferredFrom: "" };
+  if (product === "mrz" || product === "mds") return { edition: "web", inferredFrom: "" };
+  if (product !== "dbr") return { edition: "", inferredFrom: "" };
+  const text = String(query || "").toLowerCase();
+  const mentioned = [];
+  if (QUERY_EDITION_PATTERNS.mobile.test(text)) mentioned.push("mobile");
+  if (QUERY_EDITION_PATTERNS.server.test(text)) mentioned.push("server");
+  const withoutOtherJs = text.replace(NON_WEB_JS, " ");
+  if (QUERY_EDITION_PATTERNS.web.test(withoutOtherJs)) mentioned.push("web");
+  if (mentioned.length !== 1) return { edition: "", inferredFrom: "" };
+  return { edition: mentioned[0], inferredFrom: "query" };
+}
+
 export {
   sdkAliases,
   platformAliases,
@@ -421,6 +451,7 @@ export {
   isWebFrameworkPlatform,
   isWebPlatform,
   inferProductFromQuery,
+  resolveSearchScope,
   KNOWN_PLATFORMS,
   KNOWN_EDITIONS,
   validatePlatform,

package/src/server/public-offerings.js

@@ -43,6 +43,16 @@ const DBR_ONLY_EDITIONS_NOTE = `Only DBR has multiple editions; ${WEB_ONLY_OMIT_
 const API_LEVEL_NOTE = "high-level or low-level. DBR mobile ONLY; ignored for web/server/other products.";
 const PRODUCT_SELECTION_GUIDANCE = "DBR is the only product with multiple editions (mobile/web/server). DWT, DDV, MRZ, and MDS are web/JavaScript-only here, so do not ask the user which platform or language for them. api_level (high-level/low-level) applies only to DBR mobile.";
 
+// Capability facts confirmed by Dynamsoft that the docs do not state outright
+// (especially what is NOT offered). Served by get_index and the pinned
+// product-selection guidance so agents answer "do you support X?" correctly.
+const CAPABILITY_FACTS = {
+  note: "Known capability facts. They take precedence over inference; for anything not listed here, search before concluding that a capability is unsupported.",
+  ocr: "There is no standalone OCR SDK. The OCR Connector is an add-on of Dynamic Web TWAIN (DWT) and is used only together with DWT, typically on a PC or workstation. Do not recommend it for mobile or non-DWT workflows.",
+  vin: "VINs are read from their barcodes with DBR (web sample: read-vin). Reading VIN text (OCR) is not offered.",
+  idDocuments: "Passports and ID cards with an MRZ zone: MRZ. AAMVA driver licenses: DBR, which decodes the PDF417 barcode and parses the driver-license fields (web sample: read-a-drivers-license)."
+};
+
 function normalizePublicOffering(product) {
   if (!product) return "";
   const normalized = product.trim().toLowerCase();
@@ -76,6 +86,7 @@ export {
   DBR_ONLY_EDITIONS_NOTE,
   API_LEVEL_NOTE,
   PRODUCT_SELECTION_GUIDANCE,
+  CAPABILITY_FACTS,
   normalizePublicOffering,
   getHydrationProduct,
   isKnownPublicOffering,

package/src/server/resource-index/builders.js

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { extname, join } from "node:path";
 import { DDV_PREFERRED_ENTRY_FILES } from "./config.js";
 import { shortDocPath } from "./docs-loader.js";
-import { PRODUCT_SELECTION_GUIDANCE, PUBLIC_OFFERING_PRODUCTS } from "../public-offerings.js";
+import { CAPABILITY_FACTS, PRODUCT_SELECTION_GUIDANCE, PUBLIC_OFFERING_PRODUCTS } from "../public-offerings.js";
 
 const MRZ_MATCHER = /(?:\bmrz\b|machine[-\s]?readable[-\s]?zone|passport)/i;
 const MDS_MATCHER = /(?:document[-\s]scan|document scanner|document scanning|document normalizer|document normalization|normaliz|auto[-\s]?capture|crop|cropping|deskew)/i;
@@ -93,7 +93,15 @@ function buildProductSelectionGuidanceText() {
     "- MRZ Scanner (MRZ): use for passport and machine-readable-zone workflows. Public guidance is web/mobile solution/RTU only. Do not default to a foundational API path here; handle server/desktop separately through contact-driven guidance.",
     "- Mobile Document Scanner (MDS): use for document scan and normalization workflows. Public guidance is web-only solution/RTU. Do not default to a foundational API path here; handle mobile and server/desktop separately through contact-driven guidance.",
     "",
-    "Choose DBR when you want direct barcode capabilities, MRZ when you want passport/MRZ flows, MDS when you want document scanning flows, DWT when you need browser acquisition, and DDV when you need viewing, annotation, multi-page handling, or PDF-oriented extension paths."
+    "Choose DBR when you want direct barcode capabilities, MRZ when you want passport/MRZ flows, MDS when you want document scanning flows, DWT when you need browser acquisition, and DDV when you need viewing, annotation, multi-page handling, or PDF-oriented extension paths.",
+    "",
+    "## Known Capability Facts",
+    "",
+    CAPABILITY_FACTS.note,
+    "",
+    `- OCR: ${CAPABILITY_FACTS.ocr}`,
+    `- VIN: ${CAPABILITY_FACTS.vin}`,
+    `- ID documents: ${CAPABILITY_FACTS.idDocuments}`
   ].join("\n");
 }
 
@@ -428,6 +436,7 @@ function buildIndexData({
       productSelection: {
         guidance: PRODUCT_SELECTION_GUIDANCE,
         publicOfferings: [...PUBLIC_OFFERING_PRODUCTS],
+        capabilities: { ...CAPABILITY_FACTS },
         offerings: {
           dwt: {
             name: "Dynamic Web TWAIN",
@@ -506,6 +515,7 @@ function buildIndexData({
     productSelection: {
       guidance: PRODUCT_SELECTION_GUIDANCE,
       publicOfferings: [...PUBLIC_OFFERING_PRODUCTS],
+      capabilities: { ...CAPABILITY_FACTS },
       dcvSupersetSummary: "Dynamsoft Capture Vision (DCV) aggregates Dynamsoft Barcode Reader (DBR), Dynamsoft Label Recognizer (DLR), Dynamsoft Document Normalizer (DDN), Dynamsoft Code Parser (DCP), and Dynamsoft Camera Enhancer (DCE) into one pipeline. DCV is internal only and is not a selectable public product.",
       useDbrWhen: [
         "Barcode-only workflows where DCV-specific workflows are not required."

package/src/server/tools/register-document-tools.js

@@ -13,10 +13,11 @@ export function registerDocumentTools({ server, readIndexedResource }) {
         "Read the full text of a Dynamsoft documentation page by its doc:// URI.",
         "",
         "WHEN TO USE:",
-        "- After search returns doc:// results: call read_document with the exact uri from a resource_link or the plain URI list before answering.",
-        "- When you need the actual article body (API details, parameters, code snippets) instead of the search summary.",
+        "- After search returns doc:// results whose matched passages do not cover the question: call read_document with the exact uri from a resource_link or the plain URI list before answering.",
+        "- When you need the full article (complete API details, parameter lists, code with its original formatting) rather than a matched passage or summary.",
         "",
         "WHEN NOT TO USE:",
+        "- When a matched passage returned by search already answers the question; cite that result's public URL instead.",
         "- For sample:// URIs, use get_sample_files with resource_uri instead (complete sample projects).",
         "- Do not construct or edit doc:// URIs yourself; they are generated by search and may change across data refreshes.",
         "",

package/src/server/tools/register-index-tools.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { SEARCH_PASSAGE_COUNT, buildSearchResultsResponse, createHitDescriber, runScopedSearch } from "../helpers/search-response.js";
 import { formatScoreLabel, formatScoreNote } from "../helpers/server-helpers.js";
 import {
   buildUnknownPublicProductResponse,
@@ -8,7 +9,7 @@ import {
   WEB_ONLY_OMIT_NOTE
 } from "../public-offerings.js";
 import { buildUnsupportedPublicScopeResponse } from "./public-routing.js";
-import { validatePlatform, validateEdition } from "../normalizers.js";
+import { resolveSearchScope, validatePlatform, validateEdition } from "../normalizers.js";
 
 export function registerIndexTools({
   server,
@@ -25,28 +26,7 @@ export function registerIndexTools({
   getSampleEntries,
   getSampleSuggestions
 }) {
-  // Build a resource_link description that lets an agent choose WITHOUT a
-  // follow-up read: type | scope | version | score - summary, then the matched
-  // snippet and canonical URL when available (issue #146).
-  function buildHitDescription(entry) {
-    const versionLabel = entry.version ? `v${entry.version}` : "n/a";
-    const scopeLabel = formatScopeLabel(entry);
-    const sampleId = entry.type === "sample" ? getSampleIdFromUri(entry.uri) : "";
-    const sampleHint = sampleId ? ` | sample_id: ${sampleId}` : "";
-    const scoreLabel = formatScoreLabel(entry);
-    const sharedLabel = entry.type === "doc" && Array.isArray(entry.tags) && entry.tags.includes("shared")
-      ? ` | shared Capture Vision API used by DBR (DCV v${entry.sourceVersion || "n/a"})`
-      : "";
-    let desc = `${entry.type.toUpperCase()} | ${scopeLabel} | ${versionLabel}${sharedLabel}${scoreLabel} - ${entry.summary}${sampleHint}`;
-    if (entry.matchedSnippet) {
-      const snippet = String(entry.matchedSnippet).replace(/\s+/g, " ").slice(0, 220);
-      desc += ` — "${snippet}"`;
-    }
-    if (entry.type === "doc" && entry.url) {
-      desc += ` | ${entry.url}`;
-    }
-    return desc;
-  }
+  const buildHitDescription = createHitDescriber({ formatScopeLabel, getSampleIdFromUri });
 
   function looksLikeSampleIdQuery(value) {
     const normalized = String(value || "").trim();
@@ -119,8 +99,9 @@ export function registerIndexTools({
         "- version: Version constraint (e.g. '10', '11.x'). Only latest major is served by default.",
         "- type: 'doc', 'sample', 'index', 'policy', or 'any' (default). Use 'sample' to restrict to sample results.",
         "- limit: 1-10 (default 5). Max number of results.",
+        `- content: 'passage' (default) includes the matched passage (up to ~1500 chars) of the top ${SEARCH_PASSAGE_COUNT} results; 'none' returns links and short snippets only.`,
         "",
-        "RETURNS: An MCP response whose content array includes a leading text summary item followed by zero or more resource_link items with URIs. For doc:// URIs, call read_document with the exact returned uri to get the full document text before answering. For sample:// URIs, call get_sample_files with resource_uri to get the full project files.",
+        "RETURNS: An MCP response whose content array includes a leading text summary item, zero or more resource_link items with URIs, and (unless content='none') a text item with the matched passages of the top results. Answer from a passage when it covers the question; otherwise, for doc:// URIs call read_document with the exact returned uri to get the full document text. For sample:// URIs, call get_sample_files with resource_uri to get the full project files.",
         "",
         "RELATED TOOLS: get_index (discover products first), list_samples (browse all samples), read_document (read a doc:// result), get_sample_files (retrieve full sample project files)."
       ].join("\n"),
@@ -131,7 +112,8 @@ export function registerIndexTools({
         platform: z.string().optional().describe(`Platform (DBR only spans multiple): android, ios, maui, react-native, flutter, js, python, cpp, java, dotnet, nodejs, angular, blazor, capacitor, electron, es6, native-ts, next, nuxt, pwa, react, requirejs, svelte, vue, webview, spm, core. ${WEB_ONLY_OMIT_NOTE}`),
         version: z.string().optional().describe("Version constraint (major or full version)"),
         type: z.enum(["doc", "sample", "index", "policy", "any"]).optional(),
-        limit: z.number().int().min(1).max(10).optional().describe("Max results (default 5)")
+        limit: z.number().int().min(1).max(10).optional().describe("Max results (default 5)"),
+        content: z.enum(["passage", "none"]).optional().describe(`'passage' (default): include the matched passage of the top ${SEARCH_PASSAGE_COUNT} results. 'none': links and short snippets only.`)
       },
       annotations: {
         readOnlyHint: true,
@@ -140,7 +122,7 @@ export function registerIndexTools({
         openWorldHint: false
       }
     },
-    async ({ query, product, edition, platform, version, type, limit }) => {
+    async ({ query, product, edition, platform, version, type, limit, content: contentMode }) => {
       const normalizedProduct = normalizeProduct(product);
       if (product && !isKnownPublicOffering(normalizedProduct)) {
         return buildUnknownPublicProductResponse(product);
@@ -162,9 +144,21 @@ export function registerIndexTools({
       const unsupportedScopeResponse = buildUnsupportedPublicScopeResponse(normalizedProduct, normalizedEdition, normalizedPlatform);
       if (unsupportedScopeResponse) return unsupportedScopeResponse;
 
-      await ensureScopeHydrated({
+      // MRZ/MDS are served for web only: hydration, exact sample matches,
+      // sample suggestions, and ranked search all use the web default (an
+      // unfiltered MRZ scope would otherwise download the mobile repos in lazy
+      // mode). DBR editions are read from the query only for ranked search.
+      // Version policy keeps the scope exactly as the caller gave it.
+      const defaultEdition = resolveSearchScope({
+        query: "",
         product: normalizedProduct,
         edition: normalizedEdition,
+        platform: normalizedPlatform
+      }).edition;
+
+      await ensureScopeHydrated({
+        product: normalizedProduct,
+        edition: defaultEdition,
         platform: normalizedPlatform,
         type: type || "any"
       });
@@ -182,14 +176,13 @@ export function registerIndexTools({
       }
 
       const maxResults = Math.min(limit || 5, 10);
-
       // Exact sample-ID fast path (when searching for samples)
       const effectiveType = type || "any";
       if (effectiveType === "sample" || effectiveType === "any") {
         const normalizedQuery = normalizeSampleName(query);
         const scopedSamples = getSampleEntries({
           product: normalizedProduct,
-          edition: normalizedEdition,
+          edition: defaultEdition,
           platform: normalizedPlatform
         });
         const exactMatches = scopedSamples.filter((entry) => {
@@ -243,9 +236,9 @@ export function registerIndexTools({
       const preferSampleSuggestionFallback =
         effectiveType === "sample" && looksLikeSampleIdQuery(query);
 
-      const topResults = preferSampleSuggestionFallback
-        ? []
-        : await searchResources({
+      const { results: topResults, scopeNote } = preferSampleSuggestionFallback
+        ? { results: [], scopeNote: "" }
+        : await runScopedSearch(searchResources, {
             query,
             product: normalizedProduct,
             edition: normalizedEdition,
@@ -260,7 +253,7 @@ export function registerIndexTools({
           const suggestions = await getSampleSuggestions({
             query,
             product: normalizedProduct,
-            edition: normalizedEdition,
+            edition: defaultEdition,
             platform: normalizedPlatform,
             limit: maxResults
           });
@@ -315,52 +308,15 @@ export function registerIndexTools({
         };
       }
 
-      // Capture Vision / DCV is the umbrella framework, not a selectable public
-      // product — steer the agent to the right offering (issue #150).
-      const dcvUmbrella = /\b(capture[\s-]?vision|dcv)\b/i.test(query) && !normalizedProduct;
-      const readGuidance = "For doc:// results, call read_document with the exact uri to get the document text; for sample:// results, call get_sample_files with resource_uri.";
-      const leadText = dcvUmbrella
-        ? `"Capture Vision" (DCV) is Dynamsoft's umbrella framework — pick the public product for your task: DBR (barcodes), MRZ (passports/IDs), MDS (document capture), DWT (scanner hardware), DDV (document viewer). Results below span the closest matches.\nFound ${topResults.length} result(s) for "${query}". ${readGuidance}`
-        : `Found ${topResults.length} result(s) for "${query}". ${readGuidance}`;
-      const content = [
-        {
-          type: "text",
-          text: leadText
-        }
-      ];
-
-      for (const entry of topResults) {
-        const versionLabel = entry.version ? `v${entry.version}` : "n/a";
-        const scopeLabel = formatScopeLabel(entry);
-        const sampleId = entry.type === "sample" ? getSampleIdFromUri(entry.uri) : "";
-        const sampleHint = sampleId ? ` | sample_id: ${sampleId}` : "";
-        const scoreLabel = formatScoreLabel(entry);
-        content.push({
-          type: "resource_link",
-          uri: entry.uri,
-          name: entry.title,
-          description: buildHitDescription(entry),
-          mimeType: entry.mimeType,
-          annotations: {
-            audience: ["assistant"],
-            priority: 0.8
-          }
-        });
-      }
-
-      const plainLines = topResults.map((entry, index) => {
-        const sampleId = entry.type === "sample" ? getSampleIdFromUri(entry.uri) : "";
-        const action = entry.type === "sample" ? "get_sample_files resource_uri" : "read_document uri";
-        const sampleNote = sampleId ? ` sample_id=${sampleId}` : "";
-        const scoreNote = formatScoreNote(entry);
-        return `- ${index + 1}. ${entry.uri}${sampleNote}${scoreNote} (${action})`;
-      });
-      content.push({
-        type: "text",
-        text: ["Plain URIs (copy/paste):", ...plainLines].join("\n")
+      return buildSearchResultsResponse({
+        query,
+        results: topResults,
+        contentMode,
+        product: normalizedProduct,
+        scopeNote,
+        describeHit: buildHitDescription,
+        getSampleIdFromUri
       });
-
-      return { content };
     }
   );
 }