@pipeshub-ai/mcp 2.2.0 → 2.3.0

package/src/tool-names.ts

@@ -6,11 +6,11 @@ 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.\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`."
+    "description": "Ask a question, get an answer grounded in the org's indexed data with\ncitations. It reads a few retrieved passages — never a whole document,\nnever a complete list.\n\n**Three questions this tool gets WRONG. Check them first:**\n- **Structure** — \"what's under this epic?\", \"which pages are in this\n  space?\", \"what links to this ticket?\", \"what's in this folder?\" →\n  `pipeshub_get_record_content` `mode:\"navigate\"`. Ranking cannot see how\n  records relate.\n- **Exhaustive** — \"how many X?\", \"list ALL the Y\", \"every Z\" →\n  `mode:\"navigate\"`, which reports the group's real total. This tool\n  undercounts and will not say so.\n- **One named document** — summarize it, extract from it, what does it say\n  about X → `pipeshub_search` for the `recordId`, then `mode:\"content\"`.\n\nEverything else about the org's knowledge belongs here: policies,\nprocesses, decisions, history, \"what do we know about X\", and any question\nspanning several documents.\n\n**Internal search** (default, `chatMode: \"internal_search\"`): the user's\ndocuments, files, knowledge base, company policies — anything in their\nPipesHub-indexed sources (Drive, Box, Confluence, Slack, Gmail, Jira, the\norg's KB, ...).\n\n**Web search** (`chatMode: \"web_search\"`): current events or public\ninformation unlikely to be in the org's knowledge base.\n\nBoth are plain-chat modes. **Agent chat** — pass an `agentId` from\n`pipeshub_agents` — runs against that agent's own prompt, tools and knowledge;\n`quick` is its only mode, requires the `agentId`, and is sent automatically.\n\n- \"What's our policy on Y?\" → `pipeshub_chat` (internal_search)\n- \"What's in the news about Z?\" → `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 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)."
+    "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)."
   },
   {
     "name": "pipeshub_download_record",
@@ -18,7 +18,7 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "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."
+    "description": "Three operations on the org's records. Pick by what you hold:\n\n  `mode:\"lookup\"`   — a URL, issue key (PA-1787), or external ID\n                    → its recordId plus the record's metadata\n  `mode:\"navigate\"` — a question about structure: what is under X,\n                    what links to Y → browses the hierarchy\n  `mode:\"content\"`  — a recordId, and you need the document's COMPLETE text\n\n**`mode:\"content\"` (default)** — the only way to see a document's complete\ntext. Use it whenever missing part of the document could make the answer\nwrong: summarize, extract or list ALL of something, check whether or where\na doc mentions X, review, or compare named docs. `pipeshub_chat` cannot do\nthese — it never sees a whole document.\n\nJudge by the user's INTENT, not their keywords: \"what's this doc about?\",\n\"walk me through the report\", \"anything in here about Y?\" are all\nfull-content tasks. Get the `recordId` from a `pipeshub_search` top hit, a\nchat citation, or `mode:\"lookup\"`.\n\nReturns one `content` string: a metadata header (title, source, key fields,\npre-generated summary) then the full parsed text. A record with no\nextractable content returns the literal `No record found`. Use\n`pipeshub_download_record` only for the original file bytes.\n\n**`mode:\"navigate\"`** — browse the hierarchy: RecordGroup (project /\nspace / drive / folder) → Record (epic / story / page / file) → children,\nwith breadcrumbs, related links and record IDs.\n\nUse it when the question depends on structure rather than wording: what is\nunder this epic, which pages sit in this space, what is linked to this\nticket, what is in this folder — and every \"how many\" / \"all of\" / \"every\"\nquestion. Search ranks by content; only this shows how records relate, and\nonly this gives a count you can trust.\n\nOmit `nodeId` for a flat listing of everything reachable, most recently\nupdated first — the usual starting point. A URL, an issue key, or a\n`pipeshub_sources` id also works and resolves automatically.\n\nPass `depth:2` or `depth:3` to see several levels in ONE call — an epic's\nstories AND their subtasks, a space's pages AND their children — instead of\none call per level. Use it whenever the question needs an overview of a\nhierarchy rather than a single node.\n\nOpening a record also prints that record's own metadata — for a ticket,\nstatus, assignee, priority and dates — so a question about one record is\noften answered by this call alone. It returns no document text; for that,\nre-call with `mode:\"content\"`.\n\nReturns `Path` breadcrumbs, the current node's metadata, a children listing\ncarrying `record_id=` or `node_id=` per row plus the group's total\n(`Children 1-50 of 61`), `Related` cross-references, and a `Next:` line.\nOne page is usually every child, so only pass `page:2` when that `Next:`\nline says more exist.\n\n**`mode:\"lookup\"`** — turn an external reference into a recordId, the first\nstep whenever the question names one. Returns that record's metadata (for a\nticket: status, assignee, priority, dates) plus its recordId, which\n`mode:\"navigate\"` takes to list what is under it and `mode:\"content\"` takes\nto read it.\n\nHandles Jira keys and URLs, Confluence, Drive, Slack permalinks, Linear,\nNotion, ServiceNow sys_id, SharePoint, Gmail/Outlook, and any connector\nwhose records index a web URL. Resolution searches ALL connectors you can\naccess, regardless of any source filter you used elsewhere.\n\nA miss is a 200 with empty `matches` and the input echoed in\n`not_found_identifiers` — that may mean no-access, not non-existence. Use\n`mode:\"navigate\"` to confirm the record exists before telling the user it\ndoes not. If `ambiguous` is true, pick from `matches` rather than taking\nthe first.\n\nNavigate and lookup return a rendered text view whose closing `Next:` line\nnames the exact follow-up call — follow it. When presenting a record, link\nit using the `Web URL` from its metadata header (when present)."
   },
   {
     "name": "pipeshub_directory",