@pipeshub-ai/mcp 2.0.1 → 2.2.0

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

@@ -1,9 +1,3 @@
-// Curated PipesHub chat tool. Hand-written; replaces the two generated
-// tools `pipeshub-chat` (create) and `pipeshub-chat-continue` (follow-up)
-// with a single tool that branches on whether `conversationId` was given.
-//
-// Wire transport: SSE. The non-streaming `/conversations/create` endpoint
-// is broken in production today, so we drive
 // `POST /conversations/stream` (and
 // `POST /conversations/{conversationId}/messages/stream` for follow-ups),
 // accumulate the frames server-side, and hand the LLM a single trimmed
@@ -29,9 +23,12 @@
 import * as z from "zod";
 import { conversationsStreamConversation } from "../../funcs/conversationsStreamConversation.js";
 import { conversationsStreamMessage } from "../../funcs/conversationsStreamMessage.js";
+import { agentsStreamConversation } from "../../funcs/agentsStreamConversation.js";
+import { agentsStreamMessage } from "../../funcs/agentsStreamMessage.js";
 import { ToolDefinition } from "../tools.js";
 import {
   errorResult,
+  httpErrorResult,
   iterateSSE,
   jsonResult,
   trimConversation,
@@ -68,16 +65,28 @@ const args = {
   ),
   modelName: z.string().optional(),
   modelFriendlyName: z.string().optional(),
-  chatMode: z.enum(["web_search", "internal_search"]).optional().describe(
-    "Controls retrieval source. "
-      + "`internal_search` (default) — searches the org's indexed knowledge "
-      + "bases (Drive, Confluence, Slack, Gmail, Jira, Box, etc.) and returns "
-      + "citations. Use this for questions about internal docs, policies, or "
-      + "company data. "
-      + "`web_search` — searches the public web instead of internal sources. "
-      + "Use only when the user explicitly asks about current events, public "
-      + "information, or anything not expected to be in the org's KB. "
-      + "Omit this field (or pass `internal_search`) for all normal queries.",
+  agentId: z.string().optional().describe(
+    "Optional PipesHub agent to converse with — the `agentId` from "
+      + "`pipeshub_agents`. When set, this turn runs against that agent's "
+      + "configuration (prompt, tools, knowledge). On follow-up turns pass the "
+      + "SAME `agentId` together with the `conversationId` returned by the "
+      + "previous call. Omit for a plain (non-agent) conversation. If unsure "
+      + "which agent to use, call `pipeshub_agents` first to see the options.",
+  ),
+  chatMode: z.enum([
+    "internal_search",
+    "web_search",
+    "auto",
+    "quick",
+    "verification",
+    "deep",
+  ]).optional().describe(
+    "Response strategy. The valid values depend on whether `agentId` is set:\n"
+      + "- WITHOUT `agentId` (plain chat): `internal_search` — answer from the "
+      + "org's indexed knowledge (default) — or `web_search` — answer from the "
+      + "live web.\n"
+      + "- WITH `agentId` (agent chat): `auto` (let the agent decide; default), "
+      + "`quick`, `verification`, or `deep`.",
   ),
 };
 
@@ -91,6 +100,9 @@ the user asks about their documents, files, knowledge base, company policies,
 or anything that could plausibly be answered by content in their PipesHub-indexed
 sources (Drive, Box, Confluence, Slack, Gmail, Jira, the org's KB, ...).
 Grounds the answer in the user's actual data and returns citations.
+Answers come from a few retrieved passages, not whole documents — for
+any task needing a document's full content, use
+\`pipeshub_get_record_content\` instead.
 
 **Web search** (\`chatMode: "web_search"\`): Use when the user asks about
 current events, public information, or anything unlikely to be in the org's
@@ -98,8 +110,11 @@ internal knowledge base. Pass \`chatMode: "web_search"\` and this tool will
 search the public web instead.
 
 **When to pick this over other tools:**
-- "What does <document> say about X?" → \`pipeshub_chat\` (internal_search)
-- "Summarize <topic / doc>." → \`pipeshub_chat\` (internal_search)
+- "Summarize <doc>" / "key points of <doc>" / "what does <document> say
+  about X?" → NOT this tool. Use \`pipeshub_search\` →
+  \`pipeshub_get_record_content\`: answering for a specific document
+  requires its full content, and chat only sees a few retrieved
+  passages, never the whole document.
 - "What's our policy on Y?" → \`pipeshub_chat\` (internal_search)
 - "What's in the news about Z?" → \`pipeshub_chat\` (web_search)
 - "What is the latest version of <library>?" → \`pipeshub_chat\` (web_search)
@@ -134,8 +149,42 @@ cited document, take \`citations[*].recordId\` and call
     const fetchOptions = { signal: ctx.signal };
     let response: Response;
 
-    if (args.conversationId) {
-      // Continue an existing conversation.
+    if (args.agentId) {
+      // Agent conversation. Agent chatMode vocabulary defaults to `auto`.
+      const agentChatMode = args.chatMode ?? "auto";
+      if (args.conversationId) {
+        // Continue an existing agent conversation.
+        const [result] = await agentsStreamMessage(client, {
+          agentKey: args.agentId,
+          conversationId: args.conversationId,
+          body: {
+            query: args.query,
+            modelKey: args.modelKey,
+            modelName: args.modelName,
+            modelFriendlyName: args.modelFriendlyName,
+            chatMode: agentChatMode,
+          },
+        }, { fetchOptions }).$inspect();
+        if (!result.ok) return errorResult(result.error.message);
+        response = result.value;
+      } else {
+        // Start a new agent conversation.
+        const [result] = await agentsStreamConversation(client, {
+          agentKey: args.agentId,
+          body: {
+            query: args.query,
+            filters: args.filters,
+            modelKey: args.modelKey,
+            modelName: args.modelName,
+            modelFriendlyName: args.modelFriendlyName,
+            chatMode: agentChatMode,
+          },
+        }, { fetchOptions }).$inspect();
+        if (!result.ok) return errorResult(result.error.message);
+        response = result.value;
+      }
+    } else if (args.conversationId) {
+      // Continue an existing (non-agent) conversation.
       const [result] = await conversationsStreamMessage(client, {
         conversationId: args.conversationId,
         body: {
@@ -143,25 +192,31 @@ cited document, take \`citations[*].recordId\` and call
           modelKey: args.modelKey,
           modelName: args.modelName,
           modelFriendlyName: args.modelFriendlyName,
-          chatMode: args.chatMode,
+          chatMode: args.chatMode ?? "internal_search",
         },
       }, { fetchOptions }).$inspect();
       if (!result.ok) return errorResult(result.error.message);
       response = result.value;
     } else {
-      // Start a new conversation.
+      // Start a new (non-agent) conversation.
       const [result] = await conversationsStreamConversation(client, {
         query: args.query,
         filters: args.filters,
         modelKey: args.modelKey,
         modelName: args.modelName,
         modelFriendlyName: args.modelFriendlyName,
-        chatMode: args.chatMode,
+        chatMode: args.chatMode ?? "internal_search",
       }, { fetchOptions }).$inspect();
       if (!result.ok) return errorResult(result.error.message);
       response = result.value;
     }
 
+    // The streaming funcs accept any HTTP status as a "successful request",
+    // so explicitly reject non-2xx (auth, not-found, server errors) with a
+    // clear message before we try to read the body as SSE.
+    const httpErr = await httpErrorResult(response, "PipesHub chat request");
+    if (httpErr) return httpErr;
+
     // Drain the SSE stream. We only need the terminal `complete` (or
     // `error`) frame; everything else is observability and ignored.
     let finalConversation: any = null;

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

@@ -1,4 +1,3 @@
-// Curated directory tool. Hand-written; merges four generated tools
 // (`pipeshub-list-users`, `pipeshub-get-user`, `pipeshub-list-user-groups`,
 // `pipeshub-list-my-teams`) plus a `whoami` action that decodes the bearer
 // JWT into a single tool.

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

@@ -1,7 +1,3 @@
-// Curated download tool. Hand-written; replaces the generated
-// `pipeshub-download-record`. Pipes raw bytes back through formatResult
-// so binary downloads (PDFs, images) are returned correctly.
-
 import * as z from "zod";
 import { recordsStreamRecordBuffer } from "../../funcs/recordsStreamRecordBuffer.js";
 import { formatResult, ToolDefinition } from "../tools.js";

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

@@ -0,0 +1,67 @@
+import * as z from "zod";
+import { connectorGetRecordContent } from "../../funcs/connectorGetRecordContent.js";
+import { ToolDefinition } from "../tools.js";
+import { errorResult, httpErrorResult, readJson } from "./_helpers.js";
+
+const args = {
+  recordId: z.string().min(1).describe(
+    "Record identifier — usually a UUID for connector-sourced records or "
+      + "a 24-character ObjectId for uploaded records. Get it from a chat "
+      + "citation (`citations[*].recordId`) or from a `pipeshub_search` hit.",
+  ),
+};
+
+export const tool$pipeshubGetRecordContent: ToolDefinition<typeof args> = {
+  name: "pipeshub_get_record_content",
+  description:
+    `Read a record's full parsed content by \`recordId\` — the only way to
+see a document's COMPLETE text.
+
+Use it whenever the answer depends on a document's full content — any
+task where missing a part could make the answer wrong: summarize / key
+points / action items; extract or list ALL of something; check whether
+or where the doc mentions X; translate, rewrite, outline, or review the
+doc; compare named docs (fetch each); any question scoped to one named
+document. \`pipeshub_chat\` cannot do these — it only sees a few
+retrieved passages, never the whole document. Get the \`recordId\` from
+a \`pipeshub_search\` top hit or a chat citation.
+
+Judge by the user's INTENT, not their keywords: they need not say
+"summarize", "key points", or "extract". Reason about what a good
+answer requires — if it would need the whole document (e.g. "what's
+this doc about?", "walk me through the report", "anything in here
+about Y?"), that is a full-content task, so call this tool.
+
+Returns a single \`content\` string: a short metadata header (title,
+source, key fields, and a pre-generated summary) followed by the
+record's full parsed text — paragraphs, tables, and lists in reading
+order. For a record with no extractable content, \`content\` is the
+literal \`No record found\`. Use \`pipeshub_download_record\` only when
+you need the original file bytes.`,
+  scopes: ["read"],
+  annotations: {
+    title: "Get a record's full parsed content",
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result] = await connectorGetRecordContent(client, {
+      recordId: args.recordId,
+    }, { fetchOptions: { signal: ctx.signal } }).$inspect();
+    if (!result.ok) return errorResult(result.error.message);
+
+    // The SDK func uses errorCodes:[], so any non-2xx comes back as an
+    // ok=false Response — surface it as an error rather than parsing it.
+    const httpErr = await httpErrorResult(result.value, "Get record content");
+    if (httpErr) return httpErr;
+
+    // Success: the endpoint returns { content: <string> }. Hand the LLM the
+    // plain text (real newlines), not the JSON wrapper.
+    const parsed = await readJson<{ content?: string }>(result.value);
+    if (!parsed.ok) return parsed.result;
+    return { content: [{ type: "text", text: parsed.value.content ?? "" }] };
+  },
+};

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

@@ -1,6 +1,3 @@
-// Curated semantic-search tool. Hand-written; replaces the generated
-// `pipeshub-search` tool. Trims the response to the fields the LLM
-// actually needs (recordId, recordName, score, snippet, webUrl).
 
 import * as z from "zod";
 import { semanticSearchSearch } from "../../funcs/semanticSearchSearch.js";
@@ -26,12 +23,16 @@ export const tool$pipeshubSearch: ToolDefinition<typeof args> = {
   description:
     `Vector / semantic search across the org's indexed documents.
 
-**Use this only when the user wants to LOCATE a document** — by name,
-topic, or a phrase to grep for. For "what does the document say about
-X?" or any open-ended question, use \`pipeshub_chat\` instead, which
-does the retrieval internally and grounds the answer in citations.
+**Use this when the user wants to LOCATE a document** — by name, topic,
+or a phrase to grep for — and to resolve it to a \`recordId\`. For
+open-ended questions across many documents, use \`pipeshub_chat\`
+instead, which does the retrieval internally and grounds the answer in
+citations.
 
 Typical uses:
+- Resolve a doc name / topic into a \`recordId\` for
+  \`pipeshub_get_record_content\` — step 1 of any full-document task
+  (summarize, extract, review, "what does the doc say?").
 - Resolve a filename / phrase into a \`recordId\` for
   \`pipeshub_download_record\`.
 - Show the user a ranked list of matching files when they ask "find /

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

@@ -1,8 +1,3 @@
-// Curated discovery tool. Hand-written; merges two generated tools
-// (`pipeshub-list-sources` for connectors+KB and `pipeshub-list-models`
-// for available LLMs / embedding models) into one tool, since the LLM
-// almost always wants both before the first chat turn.
-
 import * as z from "zod";
 import { knowledgeHubGetKnowledgeHubRootNodes } from "../../funcs/knowledgeHubGetKnowledgeHubRootNodes.js";
 import { aiModelsProvidersGetAvailableModelsByType } from "../../funcs/aiModelsProvidersGetAvailableModelsByType.js";

package/src/mcp-server/tools.ts

@@ -75,9 +75,22 @@ export async function formatResult(
     content = data == null
       ? []
       : [{ type: "audio", data, mimeType: contentType }];
-  } else {
+  } else if (
+    contentType.startsWith("text/")
+    || contentType.includes("json")
+    || contentType.includes("xml")
+    || contentType.includes("yaml")
+  ) {
     const text = await response.text();
     content = [{ type: "text", text }];
+  } else {
+    const blob = await valueToBase64(await response.arrayBuffer());
+    content = blob == null
+      ? []
+      : [{
+        type: "resource",
+        resource: { uri: response.url, mimeType: contentType, blob },
+      }];
   }
 
   return response.ok ? { content } : { content, isError: true };

package/src/models/agentops.ts

@@ -0,0 +1,160 @@
+// Request models for the agent
+// endpoints that the vendored SDK does not yet cover:
+//   - GET  /agents                                                   (listAgents)
+//   - POST /agents/{agentKey}/conversations/stream                   (streamAgentConversation)
+//   - POST /agents/{agentKey}/conversations/{conversationId}/messages/stream
+//                                                                    (streamAgentConversationMessage)
+// Mirrors the shapes in the canonical OpenAPI spec; reuses the existing
+// `Filters` model. Unknown fields are stripped server-side, so the shared
+// body schema is safe to reuse for both create and follow-up turns.
+
+import * as z from "zod";
+import { Filters, Filters$zodSchema } from "./filters.js";
+
+/** Query params for `GET /agents`. */
+export type ListAgentsRequest = {
+  page?: number | undefined;
+  limit?: number | undefined;
+  search?: string | undefined;
+  sortBy?: string | undefined;
+  sortOrder?: "asc" | "desc" | undefined;
+};
+
+export const ListAgentsRequest$zodSchema: z.ZodType<ListAgentsRequest> = z
+  .object({
+    page: z.int().optional(),
+    limit: z.int().optional(),
+    search: z.string().optional(),
+    sortBy: z.string().optional(),
+    sortOrder: z.enum(["asc", "desc"]).optional(),
+  });
+
+/**
+ * Shared body for the agent conversation stream endpoints. `query` is the
+ * only required field; everything else is an optional override / routing hint.
+ * `chatMode` for agents is one of `auto | quick | verification | deep`.
+ */
+export type AgentStreamConversationBody = {
+  query: string;
+  recordIds?: Array<string> | undefined;
+  filters?: Filters | undefined;
+  chatMode?: string | undefined;
+  modelKey?: string | undefined;
+  modelName?: string | undefined;
+  modelFriendlyName?: string | undefined;
+  tools?: Array<string> | undefined;
+  timezone?: string | undefined;
+  currentTime?: string | undefined;
+};
+
+export const AgentStreamConversationBody$zodSchema: z.ZodType<
+  AgentStreamConversationBody
+> = z.object({
+  query: z.string().min(1),
+  recordIds: z.array(z.string()).optional(),
+  filters: Filters$zodSchema.optional(),
+  chatMode: z.string().optional(),
+  modelKey: z.string().optional(),
+  modelName: z.string().optional(),
+  modelFriendlyName: z.string().optional(),
+  tools: z.array(z.string()).optional(),
+  timezone: z.string().optional(),
+  currentTime: z.string().optional(),
+});
+
+/** `POST /agents/{agentKey}/conversations/stream` — path param + body. */
+export type AgentStreamCreateConversationRequest = {
+  agentKey: string;
+  body: AgentStreamConversationBody;
+};
+
+export const AgentStreamCreateConversationRequest$zodSchema: z.ZodType<
+  AgentStreamCreateConversationRequest
+> = z.object({
+  agentKey: z.string().min(1),
+  body: AgentStreamConversationBody$zodSchema,
+});
+
+/**
+ * `POST /agents/{agentKey}/conversations/{conversationId}/messages/stream` —
+ * two path params + body.
+ */
+export type AgentAddMessageStreamRequest = {
+  agentKey: string;
+  conversationId: string;
+  body: AgentStreamConversationBody;
+};
+
+export const AgentAddMessageStreamRequest$zodSchema: z.ZodType<
+  AgentAddMessageStreamRequest
+> = z.object({
+  agentKey: z.string().min(1),
+  conversationId: z.string(),
+  body: AgentStreamConversationBody$zodSchema,
+});
+
+// ── Response models ──────────────────────────────────────────────────────────
+// Validated subsets of the agent responses (only the fields the curated tools
+// surface; zod strips the rest). Types are inferred from the schemas.
+//
+// As of the enriched `GET /agents`, the list item carries `toolsets` and
+// `knowledge` directly, so the curated tool no longer needs a per-agent detail
+// fetch.
+
+const AgentWebSearch$zodSchema = z.object({
+  provider: z.string().optional(),
+  providerKey: z.string().optional(),
+  providerLabel: z.string().optional(),
+});
+
+const AgentToolsetTool$zodSchema = z.object({
+  name: z.string().nullish(),
+  fullName: z.string().nullish(),
+});
+
+const AgentToolset$zodSchema = z.object({
+  name: z.string().nullish(),
+  displayName: z.string().nullish(),
+  instanceName: z.string().nullish(),
+  tools: z.array(AgentToolsetTool$zodSchema).default([]),
+});
+
+const AgentKnowledge$zodSchema = z.object({
+  name: z.string().nullish(),
+  displayName: z.string().nullish(),
+  type: z.string().nullish(),
+});
+
+/**
+ * One item of the enriched `GET /agents` list — includes `toolsets` and
+ * `knowledge` (the routing-critical capability signal). `default([])` keeps it
+ * working against an older list endpoint that doesn't return them.
+ */
+export const AgentSummary$zodSchema = z.object({
+  _key: z.string(),
+  name: z.string(),
+  description: z.string().nullish(),
+  systemPrompt: z.string().nullish(),
+  startMessage: z.string().nullish(),
+  tags: z.array(z.string()).default([]),
+  webSearch: AgentWebSearch$zodSchema.nullish(),
+  isActive: z.boolean().nullish(),
+  toolsets: z.array(AgentToolset$zodSchema).default([]),
+  knowledge: z.array(AgentKnowledge$zodSchema).default([]),
+});
+export type AgentSummary = z.infer<typeof AgentSummary$zodSchema>;
+
+const AgentListPagination$zodSchema = z.object({
+  totalItems: z.number().nullish(),
+  total: z.number().nullish(),
+  hasNext: z.boolean().nullish(),
+  hasNextPage: z.boolean().nullish(),
+});
+
+/** Envelope of `GET /agents`. */
+export const AgentListEnvelope$zodSchema = z.object({
+  success: z.boolean().nullish(),
+  agents: z.array(AgentSummary$zodSchema).default([]),
+  pagination: AgentListPagination$zodSchema.nullish(),
+});
+export type AgentListEnvelope = z.infer<typeof AgentListEnvelope$zodSchema>;

package/src/models/getrecordcontentop.ts

@@ -0,0 +1,11 @@
+import * as z from "zod";
+
+export type GetRecordContentRequest = { recordId: string };
+
+export const GetRecordContentRequest$zodSchema: z.ZodType<
+  GetRecordContentRequest
+> = z.object({
+  recordId: z.string().describe(
+    "Record ID to fetch. Obtain it from a `pipeshub_search` result (`hits[*].recordId`) or a chat citation (`citations[*].recordId`).",
+  ),
+});

package/src/tool-names.ts

@@ -6,18 +6,26 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "name": "pipeshub_chat",
-    "description": "**Primary chat tool — handles both internal knowledge queries and web search.**\n\n**Internal search** (default, `chatMode: \"internal_search\"`): Use whenever\nthe user asks about their documents, files, knowledge base, company policies,\nor anything that could plausibly be answered by content in their PipesHub-indexed\nsources (Drive, Box, Confluence, Slack, Gmail, Jira, the org's KB, ...).\nGrounds the answer in the user's actual data and returns citations.\n\n**Web search** (`chatMode: \"web_search\"`): Use when the user asks about\ncurrent events, public information, or anything unlikely to be in the org's\ninternal knowledge base. Pass `chatMode: \"web_search\"` and this tool will\nsearch the public web instead.\n\n**When to pick this over other tools:**\n- \"What does <document> say about X?\" → `pipeshub_chat` (internal_search)\n- \"Summarize <topic / doc>.\" → `pipeshub_chat` (internal_search)\n- \"What's our policy on Y?\" → `pipeshub_chat` (internal_search)\n- \"What's in the news about Z?\" → `pipeshub_chat` (web_search)\n- \"What is the latest version of <library>?\" → `pipeshub_chat` (web_search)\n- \"Find / locate the file named X\" → `pipeshub_search` (then\n  `pipeshub_download_record` if the user wants the bytes).\n\n**Conversation lifecycle** — one tool, both start and continue:\n\n- **First turn**: omit `conversationId`. The server creates a new\n  conversation; capture `conversationId` from the response.\n- **Follow-up turn**: pass the `conversationId` from the previous\n  response. Server-side context is preserved — do NOT replay earlier\n  messages, and `filters` is ignored on follow-ups (set once at\n  creation).\n\nOnly re-omit `conversationId` (start a fresh conversation) when the\nuser explicitly asks to start over / clear context.\n\nThe response contains the AI's `answer` plus `citations`. To download a\ncited document, take `citations[*].recordId` and call\n`pipeshub_download_record`."
+    "description": "**Primary chat tool — handles both internal knowledge queries and web search.**\n\n**Internal search** (default, `chatMode: \"internal_search\"`): Use whenever\nthe user asks about their documents, files, knowledge base, company policies,\nor anything that could plausibly be answered by content in their PipesHub-indexed\nsources (Drive, Box, Confluence, Slack, Gmail, Jira, the org's KB, ...).\nGrounds the answer in the user's actual data and returns citations.\nAnswers come from a few retrieved passages, not whole documents — for\nany task needing a document's full content, use\n`pipeshub_get_record_content` instead.\n\n**Web search** (`chatMode: \"web_search\"`): Use when the user asks about\ncurrent events, public information, or anything unlikely to be in the org's\ninternal knowledge base. Pass `chatMode: \"web_search\"` and this tool will\nsearch the public web instead.\n\n**When to pick this over other tools:**\n- \"Summarize <doc>\" / \"key points of <doc>\" / \"what does <document> say\n  about X?\" → NOT this tool. Use `pipeshub_search` →\n  `pipeshub_get_record_content`: answering for a specific document\n  requires its full content, and chat only sees a few retrieved\n  passages, never the whole document.\n- \"What's our policy on Y?\" → `pipeshub_chat` (internal_search)\n- \"What's in the news about Z?\" → `pipeshub_chat` (web_search)\n- \"What is the latest version of <library>?\" → `pipeshub_chat` (web_search)\n- \"Find / locate the file named X\" → `pipeshub_search` (then\n  `pipeshub_download_record` if the user wants the bytes).\n\n**Conversation lifecycle** — one tool, both start and continue:\n\n- **First turn**: omit `conversationId`. The server creates a new\n  conversation; capture `conversationId` from the response.\n- **Follow-up turn**: pass the `conversationId` from the previous\n  response. Server-side context is preserved — do NOT replay earlier\n  messages, and `filters` is ignored on follow-ups (set once at\n  creation).\n\nOnly re-omit `conversationId` (start a fresh conversation) when the\nuser explicitly asks to start over / clear context.\n\nThe response contains the AI's `answer` plus `citations`. To download a\ncited document, take `citations[*].recordId` and call\n`pipeshub_download_record`."
   },
   {
     "name": "pipeshub_search",
-    "description": "Vector / semantic search across the org's indexed documents.\n\n**Use this only when the user wants to LOCATE a document** — by name,\ntopic, or a phrase to grep for. For \"what does the document say about\nX?\" or any open-ended question, use `pipeshub_chat` instead, which\ndoes the retrieval internally and grounds the answer in citations.\n\nTypical uses:\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\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 chunks of the same record)."
+    "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\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 chunks of the same record)."
   },
   {
     "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."
   },
+  {
+    "name": "pipeshub_get_record_content",
+    "description": "Read a record's full parsed content by `recordId` — the only way to\nsee a document's COMPLETE text.\n\nUse it whenever the answer depends on a document's full content — any\ntask where missing a part could make the answer wrong: summarize / key\npoints / action items; extract or list ALL of something; check whether\nor where the doc mentions X; translate, rewrite, outline, or review the\ndoc; compare named docs (fetch each); any question scoped to one named\ndocument. `pipeshub_chat` cannot do these — it only sees a few\nretrieved passages, never the whole document. Get the `recordId` from\na `pipeshub_search` top hit or a chat citation.\n\nJudge by the user's INTENT, not their keywords: they need not say\n\"summarize\", \"key points\", or \"extract\". Reason about what a good\nanswer requires — if it would need the whole document (e.g. \"what's\nthis doc about?\", \"walk me through the report\", \"anything in here\nabout Y?\"), that is a full-content task, so call this tool.\n\nReturns a single `content` string: a short metadata header (title,\nsource, key fields, and a pre-generated summary) followed by the\nrecord's full parsed text — paragraphs, tables, and lists in reading\norder. For a record with no extractable content, `content` is the\nliteral `No record found`. Use `pipeshub_download_record` only when\nyou need the original file bytes."
+  },
   {
     "name": "pipeshub_directory",
     "description": "Look up people, groups, and teams in PipesHub. One tool with five\nactions — pick the right `action`:\n\n- `whoami` — who is the caller?  Use this whenever you need the\n  authenticated user's own id, email, or full name (e.g. before\n  `get_user` on themselves).\n- `list_users` — search / page through org users.\n- `get_user` — full `User` document for one user (requires `userId`).\n- `list_groups` — list user groups with `userCount`.\n- `list_my_teams` — teams the caller belongs to, with capability flags\n  (`canEdit` / `canDelete` / `canManageMembers`).\n\nOutput shape varies by action; see each action's docs above."
+  },
+  {
+    "name": "pipeshub_agents",
+    "description": "List the PipesHub **agents** configured for this org, each with its\ncapabilities.\n\nAgents are specialized assistants (custom system prompt, tools, knowledge\nscope). To converse with one, take its `agentId` and pass it to\n`pipeshub_chat`'s `agentId` argument.\n\nEach agent is returned as:\n`{ agentId, name, description, systemPrompt, startMessage, tags, webSearch,\nisActive, toolsets, knowledge }`.\n- `toolsets` — what the agent can DO: each `{ name, tools }` where `name`\n  is the connector (e.g. `jira`, `gmail`) and `tools` are the runnable\n  tool ids (e.g. `jira.create_issue`, `gmail.send_email`).\n- `knowledge` — what the agent can READ: each `{ name, type }` (e.g.\n  `Confluence-2` / `Confluence`).\n\n**Route on `toolsets`/`knowledge`, not the name** — names and descriptions\nare often generic or misleading. Match the request to the agent whose tools can\nactually perform it (e.g. \"create a Jira ticket\" → the agent whose toolset is\n`jira` and whose tools include `jira.create_issue`). If NO agent has a tool\nfor the requested action, say so — don't force an unrelated agent.\n\nThe list **may be empty** (no agents configured). For plain Q&A when no\nspecific agent is needed, use `pipeshub_chat` WITHOUT `agentId` and pick a\n`chatMode`: `internal_search` (org's indexed knowledge) or `web_search`\n(live web). Use `agentId` everywhere an agent is referenced."
   }
 ];