@pipeshub-ai/mcp 2.2.0 → 2.3.0

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

@@ -1,24 +1,13 @@
 // `POST /conversations/stream` (and
 // `POST /conversations/{conversationId}/messages/stream` for follow-ups),
 // accumulate the frames server-side, and hand the LLM a single trimmed
-// `CallToolResult` once the stream emits its terminal `complete` (or
-// `error`) frame.
+// `CallToolResult` once the stream reaches a terminal frame.
 //
-// Frame types we know about (from live wire traces):
-//   - connected        — handshake; ignored
-//   - status           — { status: "started" | "searching" | "processing"
-//                         | "checking_tools" | ... }; ignored (UI-only)
-//   - answer_chunk     — { content, accumulated, ... }; we keep the latest
-//                        `accumulated` as a fallback in case the stream
-//                        ends without a `complete` frame
-//   - tool_call        — model invoked an internal tool; we collect these
-//                        as observability breadcrumbs but the LLM doesn't
-//                        need them to answer
-//   - tool_success     — paired with tool_call; same treatment
-//   - complete         — terminal; payload is `{ conversation, meta }`,
-//                        matching the non-stream response shape, so we
-//                        feed it through `trimConversation` like before
-//   - error            — terminal; surface to the LLM as a tool error
+// The wire protocol is AG-UI. The legacy `connected` / `answer_chunk` /
+// `complete` / `error` vocabulary was removed with the new agent loop and is
+// never emitted. The frames that matter — CUSTOM{conversation_created},
+// TEXT_MESSAGE_CONTENT, RUN_FINISHED, RUN_ERROR — are folded by `./_agui.js`,
+// which is kept separate so the fold stays a pure function over frames.
 
 import * as z from "zod";
 import { conversationsStreamConversation } from "../../funcs/conversationsStreamConversation.js";
@@ -26,6 +15,11 @@ import { conversationsStreamMessage } from "../../funcs/conversationsStreamMessa
 import { agentsStreamConversation } from "../../funcs/agentsStreamConversation.js";
 import { agentsStreamMessage } from "../../funcs/agentsStreamMessage.js";
 import { ToolDefinition } from "../tools.js";
+import {
+  applyAGUIFrame,
+  newChatStreamState,
+  salvagedText,
+} from "./_agui.js";
 import {
   errorResult,
   httpErrorResult,
@@ -36,9 +30,11 @@ import {
 
 const FiltersShape = z.object({
   apps: z.array(z.string()).optional().describe(
-    "Source-scoping ids. Mix connector instance UUIDs with the synthetic "
-      + "`knowledgeBase_<orgId>` id (use pipeshub_sources to discover them). "
-      + "Empty / omitted means no app-side restriction.",
+    "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.",
   ),
   kb: z.array(z.string()).optional().describe(
     "Legacy / unused. Leave empty.",
@@ -76,48 +72,53 @@ const args = {
   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`.",
+      + "- WITH `agentId` (agent chat): `quick` is the only supported mode and "
+      + "is sent automatically, so this argument can be omitted.",
   ),
 };
 
 export const tool$pipeshubChat: ToolDefinition<typeof args> = {
   name: "pipeshub_chat",
   description:
-    `**Primary chat tool — handles both internal knowledge queries and web search.**
+    `Ask a question, get an answer grounded in the org's indexed data with
+citations. It reads a few retrieved passages — never a whole document,
+never a complete list.
+
+**Three questions this tool gets WRONG. Check them first:**
+- **Structure** — "what's under this epic?", "which pages are in this
+  space?", "what links to this ticket?", "what's in this folder?" →
+  \`pipeshub_get_record_content\` \`mode:"navigate"\`. Ranking cannot see how
+  records relate.
+- **Exhaustive** — "how many X?", "list ALL the Y", "every Z" →
+  \`mode:"navigate"\`, which reports the group's real total. This tool
+  undercounts and will not say so.
+- **One named document** — summarize it, extract from it, what does it say
+  about X → \`pipeshub_search\` for the \`recordId\`, then \`mode:"content"\`.
+
+Everything else about the org's knowledge belongs here: policies,
+processes, decisions, history, "what do we know about X", and any question
+spanning several documents.
 
-**Internal search** (default, \`chatMode: "internal_search"\`): Use whenever
-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.
+**Internal search** (default, \`chatMode: "internal_search"\`): the user's
+documents, files, knowledge base, company policies — anything in their
+PipesHub-indexed sources (Drive, Box, Confluence, Slack, Gmail, Jira, the
+org's KB, ...).
 
-**Web search** (\`chatMode: "web_search"\`): Use when the user asks about
-current events, public information, or anything unlikely to be in the org's
-internal knowledge base. Pass \`chatMode: "web_search"\` and this tool will
-search the public web instead.
+**Web search** (\`chatMode: "web_search"\`): current events or public
+information unlikely to be in the org's knowledge base.
+
+Both are plain-chat modes. **Agent chat** — pass an \`agentId\` from
+\`pipeshub_agents\` — runs against that agent's own prompt, tools and knowledge;
+\`quick\` is its only mode, requires the \`agentId\`, and is sent automatically.
 
-**When to pick this over other tools:**
-- "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)
 - "Find / locate the file named X" → \`pipeshub_search\` (then
   \`pipeshub_download_record\` if the user wants the bytes).
 
@@ -147,11 +148,19 @@ cited document, take \`citations[*].recordId\` and call
   args,
   tool: async (client, args, ctx) => {
     const fetchOptions = { signal: ctx.signal };
+    // `quick` is agent-only. The plain stream schemas accept internal_search /
+    // web_search / agent, so collapse anything else to the default rather than
+    // forwarding a value that path would reject.
+    const plainChatMode = args.chatMode === "web_search"
+      ? "web_search"
+      : "internal_search";
     let response: Response;
 
     if (args.agentId) {
-      // Agent conversation. Agent chatMode vocabulary defaults to `auto`.
-      const agentChatMode = args.chatMode ?? "auto";
+      // `quick` is the only value the agent stream schemas accept, and it is
+      // required — so ignore whatever the caller passed rather than forwarding
+      // a value the gateway would reject.
+      const agentChatMode = "quick" as const;
       if (args.conversationId) {
         // Continue an existing agent conversation.
         const [result] = await agentsStreamMessage(client, {
@@ -192,7 +201,7 @@ cited document, take \`citations[*].recordId\` and call
           modelKey: args.modelKey,
           modelName: args.modelName,
           modelFriendlyName: args.modelFriendlyName,
-          chatMode: args.chatMode ?? "internal_search",
+          chatMode: plainChatMode,
         },
       }, { fetchOptions }).$inspect();
       if (!result.ok) return errorResult(result.error.message);
@@ -205,7 +214,7 @@ cited document, take \`citations[*].recordId\` and call
         modelKey: args.modelKey,
         modelName: args.modelName,
         modelFriendlyName: args.modelFriendlyName,
-        chatMode: args.chatMode ?? "internal_search",
+        chatMode: plainChatMode,
       }, { fetchOptions }).$inspect();
       if (!result.ok) return errorResult(result.error.message);
       response = result.value;
@@ -217,72 +226,44 @@ cited document, take \`citations[*].recordId\` and call
     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;
-    let recordsUsed: number | undefined;
-    let lastAccumulated: string | null = null;
-    let errorMessage: string | null = null;
-
+    // Drain the AG-UI stream. `applyAGUIFrame` returns true only on a
+    // genuinely terminal frame — a sub-agent's RUN_FINISHED carries no
+    // `result` and must not end the loop.
+    const state = newChatStreamState();
     try {
       for await (const frame of iterateSSE(response)) {
-        switch (frame.event) {
-          case "complete": {
-            const d = frame.data ?? {};
-            finalConversation = d.conversation ?? null;
-            recordsUsed = d.recordsUsed ?? d.meta?.recordsUsed;
-            break;
-          }
-          case "error": {
-            const d = frame.data ?? {};
-            errorMessage = typeof d === "string"
-              ? d
-              : (d.error ?? d.message ?? frame.raw ?? "Stream error");
-            break;
-          }
-          case "answer_chunk": {
-            const d = frame.data ?? {};
-            if (typeof d.accumulated === "string") {
-              lastAccumulated = d.accumulated;
-            } else if (typeof d.content === "string") {
-              lastAccumulated = (lastAccumulated ?? "") + d.content;
-            }
-            break;
-          }
-          // status / tool_call / tool_success / connected — ignored.
-          default:
-            break;
-        }
-        if (finalConversation || errorMessage) break;
+        if (applyAGUIFrame(state, frame)) break;
       }
     } catch (e: unknown) {
       return errorResult(`SSE stream failed: ${(e as Error).message}`);
     }
 
-    if (errorMessage) return errorResult(errorMessage);
+    if (state.error) return errorResult(state.error);
 
-    if (finalConversation) {
+    if (state.conversation) {
       return jsonResult({
-        ...trimConversation(finalConversation),
-        recordsUsed,
+        ...trimConversation(state.conversation),
+        recordsUsed: state.recordsUsed,
       });
     }
 
-    // Stream ended without a terminal frame — unusual, but salvage what
-    // we accumulated so the LLM has something to work with.
-    if (lastAccumulated) {
+    // Stream ended without a terminal frame — unusual, but salvage what we
+    // accumulated so the LLM has something to work with. `conversation_created`
+    // arrives before any answer text, so a follow-up turn can still resume.
+    const salvaged = salvagedText(state);
+    if (salvaged) {
       return jsonResult({
-        conversationId: null,
-        title: null,
+        conversationId: state.conversationId,
+        title: state.title,
         status: "Inprogress",
-        answer: lastAccumulated,
+        answer: salvaged,
         confidence: null,
         citations: [],
         followUpQuestions: [],
         messageCount: 0,
-        recordsUsed,
-        warning: "Stream ended without a `complete` frame; answer is "
-          + "the last accumulated chunk and citations are unavailable.",
+        recordsUsed: state.recordsUsed,
+        warning: "Stream ended without a terminal RUN_FINISHED; answer is the "
+          + "accumulated TEXT_MESSAGE_CONTENT and citations are unavailable.",
       });
     }
 

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

@@ -1,46 +1,184 @@
 import * as z from "zod";
 import { connectorGetRecordContent } from "../../funcs/connectorGetRecordContent.js";
+import { connectorLookupRecordByIdentifier } from "../../funcs/connectorLookupRecordByIdentifier.js";
+import { connectorNavigateKnowledgeGraph } from "../../funcs/connectorNavigateKnowledgeGraph.js";
 import { ToolDefinition } from "../tools.js";
-import { errorResult, httpErrorResult, readJson } from "./_helpers.js";
+import {
+  errorResult,
+  httpErrorResult,
+  jsonResult,
+  readJson,
+} from "./_helpers.js";
+
+/**
+ * Navigate and lookup return a server-rendered `text` view alongside the
+ * structured fields. It ends in a `Next:` line naming the exact follow-up call,
+ * so hand the LLM that string; fall back to JSON if the field is missing.
+ */
+export async function renderedResult(response: Response) {
+  const parsed = await readJson<{ text?: string }>(response);
+  if (!parsed.ok) return parsed.result;
+  const text = parsed.value?.text;
+  return typeof text === "string" && text.trim().length > 0
+    ? { content: [{ type: "text" as const, text }] }
+    : jsonResult(parsed.value);
+}
 
 const args = {
-  recordId: z.string().min(1).describe(
+  mode: z.enum(["content", "navigate", "lookup"]).default("content").describe(
+    "`content` (default) reads a record's full text by `recordId`. "
+      + "`lookup` resolves a URL / issue key / external ID to a recordId. "
+      + "`navigate` browses the knowledge graph tree.",
+  ),
+
+  // mode: "content"
+  recordId: z.string().min(1).optional().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.",
+      + "citation (`citations[*].recordId`) or from a `pipeshub_search` hit. "
+      + "Required when `mode` is `content`.",
+  ),
+
+  // mode: "navigate"
+  nodeId: z.string().min(1).max(2048).optional().describe(
+    "The node to open. Take it from a `record_id=` or `node_id=` shown in a "
+      + "previous navigate or lookup response, from a search hit's `recordId`, "
+      + "or from a `pipeshub_sources` id — a KB or connector id opens that "
+      + "source directly. Omit it entirely for the flat listing of everything "
+      + "reachable, newest first — the usual starting point. A URL or an issue "
+      + "key such as `PA-1787` also works: it is resolved to its record "
+      + "automatically, so no separate lookup is needed.",
+  ),
+  page: z.int().min(1).default(1).describe("Page number, 1-indexed."),
+  limit: z.int().min(50).max(200).default(50).describe(
+    "Children per page. The minimum is 50 — smaller values are rejected "
+      + "rather than silently raised.",
+  ),
+  depth: z.int().min(1).max(3).default(1).describe(
+    "Levels of descendants to return in one call. Above 1, the listing is a "
+      + "flat list of all descendants down to that level rather than only "
+      + "direct children, and each row carries its own `level`.",
+  ),
+  nodeTypes: z.array(z.string()).optional().describe(
+    "Restrict children to these node types, e.g. `[\"record\", \"folder\"]`.",
+  ),
+  createdAfter: z.string().optional().describe(
+    "Filter children by source creation time. ISO 8601 `YYYY-MM-DD`, or a "
+      + "full datetime that MUST carry a timezone offset — a naive datetime is "
+      + "rejected rather than assumed to be UTC.",
+  ),
+  createdBefore: z.string().optional().describe(
+    "Filter children by source creation time. `YYYY-MM-DD` is inclusive of "
+      + "the whole day.",
+  ),
+  modifiedAfter: z.string().optional().describe(
+    "Filter children by source modification time. Same formats as "
+      + "`createdAfter`.",
+  ),
+  modifiedBefore: z.string().optional().describe(
+    "Filter children by source modification time. Same formats as "
+      + "`createdBefore`.",
+  ),
+
+  // mode: "lookup"
+  identifiers: z.union([
+    z.string().min(1).max(2048),
+    z.array(z.string().min(1).max(2048)).min(1).max(10),
+  ]).optional().describe(
+    "The reference(s) to resolve: a URL, an issue key such as `PA-1787`, or "
+      + "a bare external system ID. Paste each exactly as you found it — "
+      + "tracking parameters and fragments are handled. Pass a single string, "
+      + "or an array of up to 10 to resolve them in one call. Required when "
+      + "`mode` is `lookup`.",
+  ),
+  connectorName: z.string().optional().describe(
+    "Optional hint that prioritises resolution order, e.g. `JIRA`, "
+      + "`CONFLUENCE`, `GOOGLE_DRIVE`, `SLACK`. It cannot widen the search beyond the "
+      + "connectors you can already access. Useful on a retry when a lookup "
+      + "came back empty.",
   ),
 };
 
 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.`,
+    `Three operations on the org's records. Pick by what you hold:
+
+  \`mode:"lookup"\`   — a URL, issue key (PA-1787), or external ID
+                    → its recordId plus the record's metadata
+  \`mode:"navigate"\` — a question about structure: what is under X,
+                    what links to Y → browses the hierarchy
+  \`mode:"content"\`  — a recordId, and you need the document's COMPLETE text
+
+**\`mode:"content"\` (default)** — the only way to see a document's complete
+text. Use it whenever missing part of the document could make the answer
+wrong: summarize, extract or list ALL of something, check whether or where
+a doc mentions X, review, or compare named docs. \`pipeshub_chat\` cannot do
+these — it never sees a whole document.
+
+Judge by the user's INTENT, not their keywords: "what's this doc about?",
+"walk me through the report", "anything in here about Y?" are all
+full-content tasks. Get the \`recordId\` from a \`pipeshub_search\` top hit, a
+chat citation, or \`mode:"lookup"\`.
+
+Returns one \`content\` string: a metadata header (title, source, key fields,
+pre-generated summary) then the full parsed text. A record with no
+extractable content returns the literal \`No record found\`. Use
+\`pipeshub_download_record\` only for the original file bytes.
+
+**\`mode:"navigate"\`** — browse the hierarchy: RecordGroup (project /
+space / drive / folder) → Record (epic / story / page / file) → children,
+with breadcrumbs, related links and record IDs.
+
+Use it when the question depends on structure rather than wording: what is
+under this epic, which pages sit in this space, what is linked to this
+ticket, what is in this folder — and every "how many" / "all of" / "every"
+question. Search ranks by content; only this shows how records relate, and
+only this gives a count you can trust.
+
+Omit \`nodeId\` for a flat listing of everything reachable, most recently
+updated first — the usual starting point. A URL, an issue key, or a
+\`pipeshub_sources\` id also works and resolves automatically.
+
+Pass \`depth:2\` or \`depth:3\` to see several levels in ONE call — an epic's
+stories AND their subtasks, a space's pages AND their children — instead of
+one call per level. Use it whenever the question needs an overview of a
+hierarchy rather than a single node.
+
+Opening a record also prints that record's own metadata — for a ticket,
+status, assignee, priority and dates — so a question about one record is
+often answered by this call alone. It returns no document text; for that,
+re-call with \`mode:"content"\`.
+
+Returns \`Path\` breadcrumbs, the current node's metadata, a children listing
+carrying \`record_id=\` or \`node_id=\` per row plus the group's total
+(\`Children 1-50 of 61\`), \`Related\` cross-references, and a \`Next:\` line.
+One page is usually every child, so only pass \`page:2\` when that \`Next:\`
+line says more exist.
+
+**\`mode:"lookup"\`** — turn an external reference into a recordId, the first
+step whenever the question names one. Returns that record's metadata (for a
+ticket: status, assignee, priority, dates) plus its recordId, which
+\`mode:"navigate"\` takes to list what is under it and \`mode:"content"\` takes
+to read it.
+
+Handles Jira keys and URLs, Confluence, Drive, Slack permalinks, Linear,
+Notion, ServiceNow sys_id, SharePoint, Gmail/Outlook, and any connector
+whose records index a web URL. Resolution searches ALL connectors you can
+access, regardless of any source filter you used elsewhere.
+
+A miss is a 200 with empty \`matches\` and the input echoed in
+\`not_found_identifiers\` — that may mean no-access, not non-existence. Use
+\`mode:"navigate"\` to confirm the record exists before telling the user it
+does not. If \`ambiguous\` is true, pick from \`matches\` rather than taking
+the first.
+
+Navigate and lookup return a rendered text view whose closing \`Next:\` line
+names the exact follow-up call — follow it. When presenting a record, link
+it using the \`Web URL\` from its metadata header (when present).`,
   scopes: ["read"],
   annotations: {
-    title: "Get a record's full parsed content",
+    title: "Read, browse, or resolve records",
     destructiveHint: false,
     idempotentHint: true,
     openWorldHint: false,
@@ -48,9 +186,55 @@ you need the original file bytes.`,
   },
   args,
   tool: async (client, args, ctx) => {
+    const fetchOptions = { fetchOptions: { signal: ctx.signal } };
+
+    // Navigate / lookup return the rendered `text` view rather than the
+    // `{ content: <string> }` envelope that content mode unwraps.
+    if (args.mode === "navigate") {
+      const [r] = await connectorNavigateKnowledgeGraph(client, {
+        nodeId: args.nodeId,
+        page: args.page,
+        limit: args.limit,
+        depth: args.depth,
+        nodeTypes: args.nodeTypes,
+        createdAfter: args.createdAfter,
+        createdBefore: args.createdBefore,
+        modifiedAfter: args.modifiedAfter,
+        modifiedBefore: args.modifiedBefore,
+      }, fetchOptions).$inspect();
+      if (!r.ok) return errorResult(r.error.message);
+
+      const httpErr = await httpErrorResult(r.value, "Navigate knowledge graph");
+      if (httpErr) return httpErr;
+
+      return renderedResult(r.value);
+    }
+
+    if (args.mode === "lookup") {
+      const identifiers = typeof args.identifiers === "string"
+        ? [args.identifiers]
+        : args.identifiers ?? [];
+      if (identifiers.length === 0) {
+        return errorResult('`identifiers` is required when mode is "lookup".');
+      }
+      const [r] = await connectorLookupRecordByIdentifier(client, {
+        identifiers,
+        connectorName: args.connectorName,
+      }, fetchOptions).$inspect();
+      if (!r.ok) return errorResult(r.error.message);
+
+      const httpErr = await httpErrorResult(r.value, "Record lookup");
+      if (httpErr) return httpErr;
+
+      return renderedResult(r.value);
+    }
+
+    if (!args.recordId) {
+      return errorResult('`recordId` is required when mode is "content".');
+    }
     const [result] = await connectorGetRecordContent(client, {
       recordId: args.recordId,
-    }, { fetchOptions: { signal: ctx.signal } }).$inspect();
+    }, fetchOptions).$inspect();
     if (!result.ok) return errorResult(result.error.message);
 
     // The SDK func uses errorCodes:[], so any non-2xx comes back as an

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

@@ -38,10 +38,23 @@ Typical uses:
 - Show the user a ranked list of matching files when they ask "find /
   search for X".
 
+Not for structural questions — what is under this epic, which pages are
+in this space, what links to this ticket. Ranking by content cannot show
+how records relate; use \`pipeshub_get_record_content\` \`mode:"navigate"\`.
+
+**A ranked sample, never a complete list.** Hits are the top-scoring
+blocks from the best-matching records — not all blocks of any record, and
+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 chunks of the same record).`,
+(different blocks of the same record).
+
+When presenting results to the user, link each record using its
+\`webUrl\` (when present).`,
   scopes: ["read"],
   annotations: {
     title: "Semantic search",

package/src/models/lookuprecordbyidentifierop.ts

@@ -0,0 +1,26 @@
+/*
+ * Adapted from Speakeasy-generated lookuprecordbyidentifierop.
+ *
+ * Request only. The generated file also declared a `LookupRecordByIdentifierResponse`
+ * union, which pulls in further response models; the func returns a raw `Response`
+ * (errorCodes: []) and the tool parses it with `readJson`, so none of that is used
+ * here.
+ */
+
+import * as z from "zod";
+
+export type LookupRecordByIdentifierRequest = {
+  identifiers: Array<string>;
+  connectorName?: string | undefined;
+};
+
+export const LookupRecordByIdentifierRequest$zodSchema: z.ZodType<
+  LookupRecordByIdentifierRequest
+> = z.object({
+  connectorName: z.string().describe(
+    "Connector hint to prioritise resolution order, e.g. `JIRA`, `CONFLUENCE`, `GOOGLE_DRIVE`, `SLACK`. Cannot widen beyond the connectors the caller can access.",
+  ).optional(),
+  identifiers: z.array(z.string().min(1).max(2048)).min(1).max(10).describe(
+    "The references to resolve: URLs, issue keys such as `PA-1787`, or bare external system IDs. Paste each exactly as you found it — tracking parameters and fragments are handled. Up to 10 per call.",
+  ),
+});

package/src/models/navigateknowledgegraphop.ts

@@ -0,0 +1,56 @@
+/*
+ * Adapted from Speakeasy-generated navigateknowledgegraphop.
+ *
+ * Request only. The generated file also declared a `NavigateKnowledgeGraphResponse`
+ * union, which pulls in ~10 further response models; the func returns a raw
+ * `Response` (errorCodes: []) and the tool parses it with `readJson`, so none of
+ * that is used here.
+ */
+
+import * as z from "zod";
+
+export type NavigateKnowledgeGraphRequest = {
+  nodeId?: string | undefined;
+  page?: number | undefined;
+  limit?: number | undefined;
+  depth?: number | undefined;
+  nodeTypes?: Array<string> | undefined;
+  createdAfter?: string | undefined;
+  createdBefore?: string | undefined;
+  modifiedAfter?: string | undefined;
+  modifiedBefore?: string | undefined;
+};
+
+// Bounds come from the OpenAPI spec rather than the generated schema, which
+// dropped them: the endpoint 400s on `limit` outside 50-200, `depth` outside
+// 1-3, `page` below 1, or an empty `nodeId`. Rejecting client-side turns each
+// of those into a validation message instead of a round-trip.
+export const NavigateKnowledgeGraphRequest$zodSchema: z.ZodType<
+  NavigateKnowledgeGraphRequest
+> = z.object({
+  createdAfter: z.string().describe(
+    "Filter children by source creation time. ISO 8601 `YYYY-MM-DD`, or a full datetime that MUST carry a timezone offset — a naive datetime is rejected rather than assumed to be UTC.",
+  ).optional(),
+  createdBefore: z.string().describe(
+    "Filter children by source creation time. `YYYY-MM-DD` is inclusive of the whole day.",
+  ).optional(),
+  depth: z.int().min(1).max(3).describe(
+    "Levels of descendants to return in one call. Above 1, `rows` is a flat list of all descendants down to that level rather than only direct children, and each row carries its own `level`.",
+  ).optional(),
+  limit: z.int().min(50).max(200).describe(
+    "Children per page. The minimum is 50 — smaller values are rejected rather than silently raised.",
+  ).optional(),
+  modifiedAfter: z.string().describe(
+    "Filter children by source modification time.",
+  ).optional(),
+  modifiedBefore: z.string().describe(
+    "Filter children by source modification time.",
+  ).optional(),
+  nodeId: z.string().min(1).max(2048).describe(
+    "The node to open. Take it from an `id` in a previous navigate or lookup response. Omit it entirely for the flat listing of everything reachable — the usual starting point. A URL or an issue key such as `PA-1787` also works: it is resolved to its record automatically.",
+  ).optional(),
+  nodeTypes: z.array(z.string()).describe(
+    "Restrict children to these node types. Repeat the parameter for multiple types: `?nodeTypes=record&nodeTypes=folder`.",
+  ).optional(),
+  page: z.int().min(1).describe("Page number, 1-indexed.").optional(),
+});