@pipeshub-ai/mcp 2.3.3 → 2.4.1

package/src/mcp-server/tools/_helpers.ts

@@ -8,6 +8,7 @@ import { Security } from "../../models/security.js";
 import { PipeshubCore } from "../../core.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { agentsListAgents } from "../../funcs/agentsListAgents.js";
+import { knowledgeHubGetKnowledgeHubRootNodes } from "../../funcs/knowledgeHubGetKnowledgeHubRootNodes.js";
 import {
   AgentListEnvelope$zodSchema,
   AgentSummary,
@@ -536,3 +537,235 @@ export function trimSearchHit(hit: any) {
     pageNum: md.pageNum,
   };
 }
+
+// ─── Sources and search scoping ──────────────────────────────────────────────
+//
+// Search and chat each take two scoping lists, and they are not interchangeable.
+// `apps` holds connector ids; `kb` holds collection (knowledge base) ids. When
+// `apps` is set and `kb` is empty, the backend drops every collection id from
+// `apps` and searches no collection at all — so a collection id in the wrong
+// list silently returns nothing. Both kinds are UUIDs, so only the source
+// listing can tell them apart.
+
+export type SourceKind = "knowledgeBase" | "connector";
+
+export interface SourceItem {
+  id: string;
+  name: string | undefined;
+  kind: SourceKind;
+  connector: string | undefined;
+  hasChildren: boolean | undefined;
+}
+
+/** A knowledge-hub root node as a source. Collections carry `connector: "KB"`. */
+export function toSource(n: any): SourceItem {
+  return {
+    id: n?.id,
+    name: n?.name,
+    kind: n?.connector === "KB" ? "knowledgeBase" : "connector",
+    connector: n?.connector,
+    hasChildren: n?.hasChildren,
+  };
+}
+
+/**
+ * Fetch every root source (connectors and collections), paginating
+ * `GET /knowledgeBase/knowledge-hub/nodes` the same way `listAllAgents` does.
+ * A partial listing would let a misplaced id slip past the scope router, so
+ * this does not stop at the first page.
+ *
+ * `reason` is a short cause for callers that report the failure as a note
+ * rather than an error — `result` carries the full message, including an auth
+ * hint that would mislead inside a search that otherwise succeeded.
+ */
+export async function listAllSources(
+  client: PipeshubCore,
+  opts: {
+    signal?: AbortSignal | undefined;
+    maxPages?: number | undefined;
+  } = {},
+): Promise<
+  | { ok: true; sources: SourceItem[]; truncated: boolean }
+  | { ok: false; result: CallToolResult; reason: string }
+> {
+  const PAGE_SIZE = 200;
+  const maxPages = opts.maxPages ?? 5;
+  // Only set `signal` when present (exactOptionalPropertyTypes).
+  const reqOptions = opts.signal
+    ? { fetchOptions: { signal: opts.signal } }
+    : {};
+
+  const all: SourceItem[] = [];
+
+  for (let page = 1; page <= maxPages; page++) {
+    const [r] = await knowledgeHubGetKnowledgeHubRootNodes(client, {
+      page,
+      limit: PAGE_SIZE,
+    }, reqOptions).$inspect();
+    if (!r.ok) {
+      return {
+        ok: false,
+        result: errorResult(`sources: ${r.error.message}`),
+        reason: r.error.message,
+      };
+    }
+
+    const status = r.value.status;
+    const httpOk = r.value.ok;
+    const parsed = await readJson<{
+      items?: any[];
+      pagination?: { hasNext?: boolean | null } | null;
+    }>(r.value, "Knowledge base listing");
+    if (!parsed.ok) {
+      return {
+        ok: false,
+        result: parsed.result,
+        reason: httpOk ? "unreadable response" : `HTTP ${status}`,
+      };
+    }
+
+    const items = parsed.value.items ?? [];
+    all.push(...items.map(toSource));
+
+    const hasNext = parsed.value.pagination?.hasNext ?? (items.length >= PAGE_SIZE);
+    if (!hasNext || items.length === 0) {
+      return { ok: true, sources: all, truncated: false };
+    }
+  }
+
+  // Hit the page cap with more pages still available.
+  return { ok: true, sources: all, truncated: true };
+}
+
+const dedupe = (ids: readonly string[]): string[] => [...new Set(ids)];
+
+export interface SourceScope {
+  apps: string[];
+  kb: string[];
+  /** Collection ids that arrived in `apps` and were moved to `kb`. */
+  movedToKb: string[];
+  /** Connector ids that arrived in `kb` and were moved to `apps`. */
+  movedToApps: string[];
+}
+
+/**
+ * Put each id in the list the backend reads it from, whichever list the
+ * caller used. `kinds` maps a source id to what the listing says it is. An id
+ * the listing does not know stays where the caller put it. Order is kept:
+ * ids from `apps` first, then ids from `kb`. Duplicates collapse.
+ */
+export function routeSourceScope(
+  apps: readonly string[] | undefined,
+  kb: readonly string[] | undefined,
+  kinds: ReadonlyMap<string, SourceKind>,
+): SourceScope {
+  const appIds = dedupe(apps ?? []);
+  const kbIds = dedupe(kb ?? []);
+  const movedToKb = appIds.filter((id) => kinds.get(id) === "knowledgeBase");
+  const movedToApps = kbIds.filter((id) => kinds.get(id) === "connector");
+  return {
+    apps: dedupe([
+      ...appIds.filter((id) => kinds.get(id) !== "knowledgeBase"),
+      ...movedToApps,
+    ]),
+    kb: dedupe([
+      ...movedToKb,
+      ...kbIds.filter((id) => kinds.get(id) !== "connector"),
+    ]),
+    movedToKb,
+    movedToApps,
+  };
+}
+
+/** The `filters` body for `POST /search`; omitted when nothing is scoped. */
+export function searchFilters(
+  scope: { apps: string[]; kb: string[] },
+): { apps: string[]; kb: string[] } | undefined {
+  if (scope.apps.length === 0 && scope.kb.length === 0) return undefined;
+  return { apps: scope.apps, kb: scope.kb };
+}
+
+/** Notes telling the model what the router did, or could not do. */
+export function sourceScopeNotes(input: {
+  movedToKb: string[];
+  movedToApps: string[];
+  lookupError?: string | undefined;
+  unlisted?: string[] | undefined;
+}): string[] {
+  const notes: string[] = [];
+  if (input.movedToKb.length > 0) {
+    notes.push(
+      `Moved ${input.movedToKb.length} collection id(s) from apps to kb: `
+        + `${input.movedToKb.join(", ")}. Collection ids belong in kb.`,
+    );
+  }
+  if (input.movedToApps.length > 0) {
+    notes.push(
+      `Moved ${input.movedToApps.length} connector id(s) from kb to apps: `
+        + `${input.movedToApps.join(", ")}. Connector ids belong in apps.`,
+    );
+  }
+  if (input.lookupError) {
+    notes.push(
+      "Could not check the ids against the source list "
+        + `(${input.lookupError}); sent them unchanged. If this finds nothing, `
+        + "check that collection ids are in kb and connector ids in apps.",
+    );
+  }
+  if (input.unlisted && input.unlisted.length > 0) {
+    notes.push(
+      `Source list was incomplete; ${input.unlisted.join(", ")} were not `
+        + "found and were sent unchanged.",
+    );
+  }
+  return notes;
+}
+
+/**
+ * Route `apps` / `kb` for one request. Every id in either list is checked
+ * against the source listing and sent in the list the backend reads it from:
+ * collection ids in `kb`, connector ids in `apps`. The lookup costs a request,
+ * so it runs only when something is scoped. A failed lookup sends the ids
+ * unchanged and says so in `notes`.
+ */
+export async function resolveSourceScope(
+  client: PipeshubCore,
+  apps: readonly string[] | undefined,
+  kb: readonly string[] | undefined,
+  opts: {
+    signal?: AbortSignal | undefined;
+    maxPages?: number | undefined;
+  } = {},
+): Promise<{ scope: SourceScope; notes: string[] }> {
+  const unchecked = routeSourceScope(apps, kb, new Map());
+  if (unchecked.apps.length === 0 && unchecked.kb.length === 0) {
+    return { scope: unchecked, notes: [] };
+  }
+
+  const listed = await listAllSources(client, opts);
+  if (!listed.ok) {
+    return {
+      scope: unchecked,
+      notes: sourceScopeNotes({
+        movedToKb: [],
+        movedToApps: [],
+        lookupError: listed.reason,
+      }),
+    };
+  }
+
+  const kinds = new Map(listed.sources.map((s) => [s.id, s.kind] as const));
+  const scope = routeSourceScope(apps, kb, kinds);
+  const unlisted = listed.truncated
+    ? [...scope.apps, ...scope.kb].filter((id) => !kinds.has(id))
+    : [];
+  return {
+    scope,
+    notes: sourceScopeNotes({
+      movedToKb: scope.movedToKb,
+      movedToApps: scope.movedToApps,
+      unlisted,
+    }),
+  };
+}
+

package/src/mcp-server/tools/pipeshubChat.ts

@@ -25,19 +25,18 @@ import {
   httpErrorResult,
   iterateSSE,
   jsonResult,
+  resolveSourceScope,
   trimConversation,
 } from "./_helpers.js";
 
 const FiltersShape = z.object({
   apps: z.array(z.string()).optional().describe(
-    "Source-scoping ids from `pipeshub_sources` — connector instance and / "
-      + "or knowledge base ids, mixed freely. The legacy org-wide "
-      + "`knowledgeBase_<orgId>` id is still accepted on deployments that "
-      + "predate per-KB sources. Empty / omitted means no app-side "
-      + "restriction.",
+    "Connector ids to use. Get them from `pipeshub_sources`, where `kind` is "
+      + "\"connector\". Collection ids go in `kb`, not here.",
   ),
   kb: z.array(z.string()).optional().describe(
-    "Legacy / unused. Leave empty.",
+    "Collection (knowledge base) ids to use. Get them from "
+      + "`pipeshub_sources`, where `kind` is \"knowledgeBase\".",
   ),
 }).optional();
 
@@ -52,8 +51,8 @@ const args = {
       + "prior messages.",
   ),
   filters: FiltersShape.describe(
-    "Source scoping for retrieval. Pass `apps` ids from `pipeshub_sources`. "
-      + "Only meaningful on the FIRST turn (when starting a new conversation).",
+    "Which sources the answer may use. Leave out to use all sources. Only "
+      + "works on the FIRST turn; later turns keep the first turn's sources.",
   ),
   modelKey: z.string().optional().describe(
     "Model id to use (from `pipeshub_sources` `llmModels[*].modelKey`). "
@@ -156,6 +155,26 @@ cited document, take \`citations[*].recordId\` and call
       : "internal_search";
     let response: Response;
 
+    // Filters apply only when a conversation starts. Each id is sent in the
+    // list the backend reads it from (collection ids in `kb`, connector ids in
+    // `apps`). Both keys go out: on agent chat a missing key falls back to the
+    // agent's own sources. An explicit empty `{ apps: [], kb: [] }` passes
+    // through unchanged.
+    let filters = args.filters;
+    let notes: string[] = [];
+    if (!args.conversationId && filters) {
+      const resolved = await resolveSourceScope(
+        client,
+        filters.apps,
+        filters.kb,
+        { signal: ctx.signal },
+      );
+      notes = resolved.notes;
+      if (resolved.scope.apps.length > 0 || resolved.scope.kb.length > 0) {
+        filters = { apps: resolved.scope.apps, kb: resolved.scope.kb };
+      }
+    }
+
     if (args.agentId) {
       // `quick` is the only value the agent stream schemas accept, and it is
       // required — so ignore whatever the caller passed rather than forwarding
@@ -182,7 +201,7 @@ cited document, take \`citations[*].recordId\` and call
           agentKey: args.agentId,
           body: {
             query: args.query,
-            filters: args.filters,
+            filters,
             modelKey: args.modelKey,
             modelName: args.modelName,
             modelFriendlyName: args.modelFriendlyName,
@@ -210,7 +229,7 @@ cited document, take \`citations[*].recordId\` and call
       // Start a new (non-agent) conversation.
       const [result] = await conversationsStreamConversation(client, {
         query: args.query,
-        filters: args.filters,
+        filters,
         modelKey: args.modelKey,
         modelName: args.modelName,
         modelFriendlyName: args.modelFriendlyName,
@@ -244,6 +263,7 @@ cited document, take \`citations[*].recordId\` and call
       return jsonResult({
         ...trimConversation(state.conversation),
         recordsUsed: state.recordsUsed,
+        ...(notes.length > 0 ? { notes } : {}),
       });
     }
 
@@ -264,6 +284,7 @@ cited document, take \`citations[*].recordId\` and call
         recordsUsed: state.recordsUsed,
         warning: "Stream ended without a terminal RUN_FINISHED; answer is the "
           + "accumulated TEXT_MESSAGE_CONTENT and citations are unavailable.",
+        ...(notes.length > 0 ? { notes } : {}),
       });
     }
 

package/src/mcp-server/tools/pipeshubDownloadRecord.ts

@@ -10,26 +10,29 @@ const args = {
       + "citation (`citations[*].recordId`) or from a `pipeshub_search` hit.",
   ),
   convertTo: z.string().optional().describe(
-    "Optional server-side format conversion target (e.g. `pdf`). When "
-      + "omitted, the original file bytes are returned.",
+    "The only conversion target connectors honour is `application/pdf` "
+      + "(the MIME type, not `pdf`). A bare `pdf` is ignored and the "
+      + "original file is returned with no error. Omit for the file as "
+      + "stored. Does not parse the document — use "
+      + "`pipeshub_get_record_content` `mode:\"content\"` for that.",
   ),
 };
 
 export const tool$pipeshubDownloadRecord: ToolDefinition<typeof args> = {
   name: "pipeshub_download_record",
   description:
-    `Stream the binary content of a single record from PipesHub.
+    `Download the file as stored for one record — not PipesHub's parsed
+content, metadata header, or summary.
 
-Typical sources for the \`recordId\`:
-- A chat citation:
-  \`pipeshub_chat\` response → \`citations[*].recordId\`.
-- A search result:
-  \`pipeshub_search\` response → \`hits[*].recordId\` /
-  \`uniqueRecords[*].recordId\`.
+Use this when the user wants the file itself (download, attach, open).
+Get \`recordId\` from a chat citation or a \`pipeshub_search\` hit.
 
-Response \`Content-Type\` is forwarded from the upstream service —
-\`application/pdf\`, \`application/octet-stream\`, etc. Binary content is
-returned base64-encoded; text content is returned inline.`,
+Do not use this to read, summarize, or answer "what does this doc
+say?" regardless of format. That is \`pipeshub_get_record_content\`
+\`mode:"content"\`. Text formats come back inline; images, audio, and
+binary as base64.
+
+\`convertTo\` accepts only \`application/pdf\`; anything else is ignored.`,
   scopes: ["read"],
   annotations: {
     title: "Download a document by record id",

package/src/mcp-server/tools/pipeshubSearch.ts

@@ -2,19 +2,34 @@
 import * as z from "zod";
 import { semanticSearchSearch } from "../../funcs/semanticSearchSearch.js";
 import { ToolDefinition } from "../tools.js";
-import { errorResult, jsonResult, readJson, trimSearchHit } from "./_helpers.js";
+import {
+  errorResult,
+  jsonResult,
+  readJson,
+  resolveSourceScope,
+  searchFilters,
+  trimSearchHit,
+} from "./_helpers.js";
+
+/** Matches the SDK request default (`src/models/semanticsearchrequest.ts`). */
+const DEFAULT_LIMIT = 10;
 
 const args = {
   query: z.string().min(1).describe(
     "Natural language query. Vector search across the org's indexed records.",
   ),
   limit: z.number().int().min(1).max(100).optional().describe(
-    "Max number of result chunks. Default 10. Use a small value (5–10) "
-      + "when the goal is to resolve a filename / topic into a recordId.",
+    "Number of results. Default 10. Use 5–10 when you only need a "
+      + "`recordId`.",
   ),
   apps: z.array(z.string()).optional().describe(
-    "Source-scoping ids — connector instance UUIDs and / or "
-      + "`knowledgeBase_<orgId>`. Get them from `pipeshub_sources`.",
+    "Connector ids to search (for example a Jira or Google Drive connection). "
+      + "Get them from `pipeshub_sources`, where `kind` is \"connector\". "
+      + "Collection ids go in `kb`, not here.",
+  ),
+  kb: z.array(z.string()).optional().describe(
+    "Collection (knowledge base) ids to search. Get them from "
+      + "`pipeshub_sources`, where `kind` is \"knowledgeBase\".",
   ),
 };
 
@@ -48,13 +63,12 @@ not every record that matches. Never count them to answer "how many" /
 "all" / "every"; navigate the record group instead, which reports its
 real total.
 
-The response is trimmed to one row per hit:
-\`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }\`.
-Highest \`score\` first; multiple hits may share the same \`recordId\`
-(different blocks of the same record).
+By default it searches everything. To search only some sources, pass
+connector ids in \`apps\` and collection ids in \`kb\`.
 
-When presenting results to the user, link each record using its
-\`webUrl\` (when present).`,
+Each hit is one matching passage, best match first:
+\`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }\`.
+One record can appear in several hits. Link a record by its \`webUrl\`.`,
   scopes: ["read"],
   annotations: {
     title: "Semantic search",
@@ -65,10 +79,20 @@ When presenting results to the user, link each record using its
   },
   args,
   tool: async (client, args, ctx) => {
+    const limit = args.limit ?? DEFAULT_LIMIT;
+    // Each id is sent in the list the backend reads it from: a collection id
+    // in `apps` or a connector id in `kb` is dropped by the backend.
+    const { scope, notes } = await resolveSourceScope(
+      client,
+      args.apps,
+      args.kb,
+      { signal: ctx.signal },
+    );
+
     const [result] = await semanticSearchSearch(client, {
       query: args.query,
-      limit: args.limit,
-      filters: args.apps ? { apps: args.apps, kb: [] } : undefined,
+      limit,
+      filters: searchFilters(scope),
     }, { fetchOptions: { signal: ctx.signal } }).$inspect();
     if (!result.ok) return errorResult(result.error.message);
 
@@ -94,6 +118,7 @@ When presenting results to the user, link each record using its
         mimeType: r.mimeType,
         webUrl: r.webUrl,
       })),
+      ...(notes.length > 0 ? { notes } : {}),
     });
   },
 };

package/src/mcp-server/tools/pipeshubSources.ts

@@ -1,8 +1,12 @@
 import * as z from "zod";
-import { knowledgeHubGetKnowledgeHubRootNodes } from "../../funcs/knowledgeHubGetKnowledgeHubRootNodes.js";
 import { aiModelsProvidersGetAvailableModelsByType } from "../../funcs/aiModelsProvidersGetAvailableModelsByType.js";
 import { ToolDefinition } from "../tools.js";
-import { errorResult, jsonResult, readJson } from "./_helpers.js";
+import {
+  errorResult,
+  jsonResult,
+  listAllSources,
+  readJson,
+} from "./_helpers.js";
 
 const args = {
   include: z.array(z.enum(["sources", "llmModels", "embeddingModels"]))
@@ -20,20 +24,19 @@ export const tool$pipeshubSources: ToolDefinition<typeof args> = {
 
 Returns up to three sections:
 
-- \`sources\` — every connector instance the org has wired up plus the
-  synthetic \`knowledgeBase_<orgId>\` entry for the org's KB. Each
-  item's \`id\` is exactly the value to put in \`pipeshub_chat\`'s or
-  \`pipeshub_search\`'s \`apps\` filter.
+- \`sources\` — connectors (\`kind: "connector"\`) and collections
+  (\`kind: "knowledgeBase"\`). For \`pipeshub_search\` and
+  \`pipeshub_chat\`, put a connector \`id\` in \`apps\` and a collection
+  \`id\` in \`kb\`. \`sourcesTruncated: true\` means the list stopped at
+  1,000 sources.
 - \`llmModels\` — chat / generation models. Each item's \`modelKey\`
-  is the value to pass on \`pipeshub_chat\` / \`pipeshub_search\` as
-  \`modelKey\`. Pick \`isDefault: true\` unless the user asks for a
-  specific model.
+  is the value to pass on \`pipeshub_chat\` as \`modelKey\`. Pick
+  \`isDefault: true\` unless the user asks for a specific model.
 - \`embeddingModels\` — vector embedding models (only fetched when
   explicitly requested via \`include\`).
 
 Call this once at the start of a session and cache the result —
-sources and models change infrequently. \`sources\` and \`llmModels\`
-are returned by default; pass \`include\` to override.`,
+sources and models change infrequently.`,
   scopes: ["read"],
   annotations: {
     title: "List PipesHub sources and AI models",
@@ -52,20 +55,10 @@ are returned by default; pass \`include\` to override.`,
     const result: Record<string, unknown> = {};
 
     if (want("sources")) {
-      const [r] = await knowledgeHubGetKnowledgeHubRootNodes(client, {
-        page: 1,
-        limit: 200,
-      }, { fetchOptions }).$inspect();
-      if (!r.ok) return errorResult(`sources: ${r.error.message}`);
-      const parsed = await readJson<{ items?: any[] }>(r.value, "Knowledge base listing");
-      if (!parsed.ok) return parsed.result;
-      result["sources"] = (parsed.value.items ?? []).map((n: any) => ({
-        id: n.id,
-        name: n.name,
-        kind: n.connector === "KB" ? "knowledgeBase" : "connector",
-        connector: n.connector,
-        hasChildren: n.hasChildren,
-      }));
+      const listed = await listAllSources(client, { signal: ctx.signal });
+      if (!listed.ok) return listed.result;
+      result["sources"] = listed.sources;
+      if (listed.truncated) result["sourcesTruncated"] = true;
     }
 
     for (

package/src/tool-names.ts

@@ -2,7 +2,7 @@
 export const toolNames: Array<{ name: string; description: string }>= [
   {
     "name": "pipeshub_sources",
-    "description": "Discover available chat sources and AI models in one call.\n\nReturns up to three sections:\n\n- `sources` — every connector instance the org has wired up plus the\n  synthetic `knowledgeBase_<orgId>` entry for the org's KB. Each\n  item's `id` is exactly the value to put in `pipeshub_chat`'s or\n  `pipeshub_search`'s `apps` filter.\n- `llmModels` — chat / generation models. Each item's `modelKey`\n  is the value to pass on `pipeshub_chat` / `pipeshub_search` as\n  `modelKey`. Pick `isDefault: true` unless the user asks for a\n  specific model.\n- `embeddingModels` — vector embedding models (only fetched when\n  explicitly requested via `include`).\n\nCall this once at the start of a session and cache the result —\nsources and models change infrequently. `sources` and `llmModels`\nare returned by default; pass `include` to override."
+    "description": "Discover available chat sources and AI models in one call.\n\nReturns up to three sections:\n\n- `sources` — connectors (`kind: \"connector\"`) and collections\n  (`kind: \"knowledgeBase\"`). For `pipeshub_search` and\n  `pipeshub_chat`, put a connector `id` in `apps` and a collection\n  `id` in `kb`. `sourcesTruncated: true` means the list stopped at\n  1,000 sources.\n- `llmModels` — chat / generation models. Each item's `modelKey`\n  is the value to pass on `pipeshub_chat` as `modelKey`. Pick\n  `isDefault: true` unless the user asks for a specific model.\n- `embeddingModels` — vector embedding models (only fetched when\n  explicitly requested via `include`).\n\nCall this once at the start of a session and cache the result —\nsources and models change infrequently."
   },
   {
     "name": "pipeshub_chat",
@@ -10,11 +10,11 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "name": "pipeshub_search",
-    "description": "Vector / semantic search across the org's indexed documents.\n\n**Use this when the user wants to LOCATE a document** — by name, topic,\nor a phrase to grep for — and to resolve it to a `recordId`. For\nopen-ended questions across many documents, use `pipeshub_chat`\ninstead, which does the retrieval internally and grounds the answer in\ncitations.\n\nTypical uses:\n- Resolve a doc name / topic into a `recordId` for\n  `pipeshub_get_record_content` — step 1 of any full-document task\n  (summarize, extract, review, \"what does the doc say?\").\n- Resolve a filename / phrase into a `recordId` for\n  `pipeshub_download_record`.\n- Show the user a ranked list of matching files when they ask \"find /\n  search for X\".\n\nNot for structural questions — what is under this epic, which pages are\nin this space, what links to this ticket. Ranking by content cannot show\nhow records relate; use `pipeshub_get_record_content` `mode:\"navigate\"`.\n\n**A ranked sample, never a complete list.** Hits are the top-scoring\nblocks from the best-matching records — not all blocks of any record, and\nnot every record that matches. Never count them to answer \"how many\" /\n\"all\" / \"every\"; navigate the record group instead, which reports its\nreal total.\n\nThe response is trimmed to one row per hit:\n`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }`.\nHighest `score` first; multiple hits may share the same `recordId`\n(different blocks of the same record).\n\nWhen presenting results to the user, link each record using its\n`webUrl` (when present)."
+    "description": "Vector / semantic search across the org's indexed documents.\n\n**Use this when the user wants to LOCATE a document** — by name, topic,\nor a phrase to grep for — and to resolve it to a `recordId`. For\nopen-ended questions across many documents, use `pipeshub_chat`\ninstead, which does the retrieval internally and grounds the answer in\ncitations.\n\nTypical uses:\n- Resolve a doc name / topic into a `recordId` for\n  `pipeshub_get_record_content` — step 1 of any full-document task\n  (summarize, extract, review, \"what does the doc say?\").\n- Resolve a filename / phrase into a `recordId` for\n  `pipeshub_download_record`.\n- Show the user a ranked list of matching files when they ask \"find /\n  search for X\".\n\nNot for structural questions — what is under this epic, which pages are\nin this space, what links to this ticket. Ranking by content cannot show\nhow records relate; use `pipeshub_get_record_content` `mode:\"navigate\"`.\n\n**A ranked sample, never a complete list.** Hits are the top-scoring\nblocks from the best-matching records — not all blocks of any record, and\nnot every record that matches. Never count them to answer \"how many\" /\n\"all\" / \"every\"; navigate the record group instead, which reports its\nreal total.\n\nBy default it searches everything. To search only some sources, pass\nconnector ids in `apps` and collection ids in `kb`.\n\nEach hit is one matching passage, best match first:\n`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }`.\nOne record can appear in several hits. Link a record by its `webUrl`."
   },
   {
     "name": "pipeshub_download_record",
-    "description": "Stream the binary content of a single record from PipesHub.\n\nTypical sources for the `recordId`:\n- A chat citation:\n  `pipeshub_chat` response → `citations[*].recordId`.\n- A search result:\n  `pipeshub_search` response → `hits[*].recordId` /\n  `uniqueRecords[*].recordId`.\n\nResponse `Content-Type` is forwarded from the upstream service —\n`application/pdf`, `application/octet-stream`, etc. Binary content is\nreturned base64-encoded; text content is returned inline."
+    "description": "Download the file as stored for one record — not PipesHub's parsed\ncontent, metadata header, or summary.\n\nUse this when the user wants the file itself (download, attach, open).\nGet `recordId` from a chat citation or a `pipeshub_search` hit.\n\nDo not use this to read, summarize, or answer \"what does this doc\nsay?\" regardless of format. That is `pipeshub_get_record_content`\n`mode:\"content\"`. Text formats come back inline; images, audio, and\nbinary as base64.\n\n`convertTo` accepts only `application/pdf`; anything else is ignored."
   },
   {
     "name": "pipeshub_get_record_content",