Synaply

ONLY call this when the user explicitly asks to save, capture, or publish an insight. Never write merely because you judge something valuable. Capture a LESSON LEARNED or piece of TACIT KNOWLEDGE from this session into the user's Synaply workspace — the hard-won, usually-unwritten 'how it really works': a decision and its rationale, a gotcha, an outcome, a reusable takeaway that would help a future human or AI agent who picks up this work cold. Write the insight yourself from the session and DISTILL the durable knowledge — don't just summarize what happened. After the user's explicit request, call it only when you have a complete, self-contained insight worth keeping (skip trivia, chatter, and anything with no durable takeaway). You supply content only ({ title, body, type?, tags? }); the workspace owns identity and visibility — never include a tenant, user, or privacy field. For `type`, PREFER to OMIT it — untyped is fine and better than a wrong type; pass one only when the insight clearly matches an existing workspace type, never a forced/closest match. To avoid duplicating an insight that already exists, first recall the workspace's captured insights with synaply_search (scope:'insights'). The server sanitizes content and governs visibility. The response status is authoritative: `published` means it is live; `pending` means it awaits review; `blocked` means safety checks stopped it; `rejected` means workspace policy or membership denied it. Never claim it was saved or published unless the returned status says so.

share_insight

HOW THINGS ENDED — 'did it work out?', 'what shipped?', failures, retrospectives. Lists TERMINAL outcomes only (merged PRs, closed/completed issues, shipped/won work, plus semantic success/failure/completion/milestone outcomes, each with sentiment): 'what shipped last month' → flat list; 'what went well / where did we miss' → sentiment=positive/negative; 'Q3 retrospective' → entity=X + occurred bounds. Each outcome carries its artifact title + deep link — present them. An entity-anchored query with NO direct outcomes auto-widens ONE hop: scope:'neighbors' + widenedVia name the neighbors — narrate that honestly; scope:'direct' means about the entity itself. NOT for open/in-progress/state queries or finding a specific PR/issue by number (use synaply_search); for what was DECIDED use synaply_search entity=X. outcomeType accepts terminal types only (merged, closed, completed, resolved, shipped, won, abandoned, success, failure, completion, milestone). ACCESS & LIMITS: Returns only documents you have ACL access to. Does NOT bypass tenant isolation. Empty results may mean no matches OR no access — by design, there is no distinction.

THE FULL LIST, NOT A SAMPLE — 'list ALL/EVERY company', 'HOW MANY people', 'which companies did we talk to since May', 'who are all the X', 'across the whole workspace': THIS tool, not synaply_search, not per-source connectors (Gmail/Calendar/Slack/Drive) — those only SAMPLE threads; this is the COMPLETE counted set. ONE type per call, since/until window + namePrefix. DEFAULT provenance:'observed': companies = two-way correspondence; other types = organically-observed links; 'any' = every record incl. CRM. COUNTING? 'how many / how much / count of X' ⇒ countOnly:true: ONE call, ONE exact number, NO rows, NO paging — never sum pages yourself. Page only when you must NAME them ('list/show me every X'). ALWAYS scoped to the calling user's access: only entities/counts derivable from documents YOU can access. PAGINATE: pass nextCursor back as cursor until complete:true = you hold the FULL set visible to THIS caller — a page may be short/empty yet carry a cursor (keep paging; INCOMPLETE until complete:true). Count mode: exact:true = final; exact:false = total is only a FLOOR — pass atLeastCursor back and ADD the totals. Counts are viewer-visible, not global totals: visibleDocCount caps at ~25 per entity. ACCESS & LIMITS: Returns only documents you have ACL access to. Does NOT bypass tenant isolation. Empty results may mean no matches OR no access — by design, there is no distinction.

READ THE WHOLE DOCUMENT — the follow-up to a search/graph hit: pass the hit's sourceType + sourceId exactly as returned (never guess ids; this tool does not search). Returns the full indexed text plus title, deep link, and author (when known). Reads cap at ~100K chars (truncated=true + totalChars). A TRUNCATED read shows the HEAD, an in-text omission marker, then the document's END — email threads keep their NEWEST messages at the END; never describe a doc's latest content without reading past the marker. For a targeted question pass `query` — it searches the ENTIRE document (beyond the cap) and returns the matching passages; over-cap docs ALSO get a delimited '[… document tail …]' block with the doc's true ending. queryMatchCount=0 is the ONLY trustworthy 'not in this document' (never conclude absence from a truncated read). EVERY response carries reachedTail: true ONLY when the returned text includes the document's FINAL characters. reachedTail=false means you have NOT seen the doc's latest content — never assert what a document/thread 'currently' says or 'ends with' from a reachedTail=false read. A null document means the id is unknown OR not visible to you, indistinguishable by design. ACCESS & LIMITS: Returns only documents you have ACL access to. Does NOT bypass tenant isolation. Empty results may mean no matches OR no access — by design, there is no distinction.

READ SEVERAL DOCUMENTS AT ONCE — the batch form of synaply_read_document_full. After a search/graph call surfaces multiple relevant hits, pass up to 20 of their {sourceType, sourceId} refs here to read them in ONE call instead of many. Returns a `documents` array IN THE SAME ORDER as your refs: each entry is the document (title, deep link, author, text) or null when that id is unknown OR not visible to you — indistinguishable by design, and a null for one ref never affects the others. Pass `query` to read every doc in targeted passage mode (recommended for a question across several docs). Full reads are per-doc char-capped (truncated=true + totalChars when cut) and the whole response is budget-bounded — for the COMPLETE text of one long document use synaply_read_document_full. Every doc carries reachedTail: false means you have NOT seen that doc's latest content (thread tails) — re-read it individually before asserting its current state. Like that tool, this does NOT search for documents — you pass ids a prior call returned. ACCESS & LIMITS: Returns only documents you have ACL access to. Does NOT bypass tenant isolation. Empty results may mean no matches OR no access — by design, there is no distinction.

THE WORKSPACE KNOWLEDGE TOOL — every workspace question starts here: hybrid keyword+semantic search over all you can see (email, chat, files, code, calendar, CRM, people) + EXACT facets. PERSON questions: the FIRST call sets person= — 'last email from Alex' ⇒ person='Alex Moreau', role='involving', kind='email', orderBy='recent', NO query. EMAIL IS THREAD-LEVEL: role='author' = thread INITIATOR only; author→0 ⇒ retry 'involving'. identityCandidates returned ⇒ present them and ask — NEVER silently pick one. Latest/newest MUST set orderBy='recent' — 'latest' is not a search term; RECENCY COMES FROM lastActivity, never snippet dates. ENTITY overviews/decisions ('tell me about X'): entity='X' (+includeRelationships=true); anchorDoc/anchorUser = direct links. Facet miss ⇒ retry plain query text; READ the top hit before saying 'not found'. OTHER TOOLS ONLY FOR: finished work → synaply_get_outcome; full text → synaply_read_document_full. 'list all/every X' / 'how many' / 'which companies' → synaply_list_entities. Everything else incl. 'what integration/vendor/approach did we land on for <client>' = THIS tool. Full playbook: server instructions. ACCESS & LIMITS: Returns only documents you have ACL access to. Does NOT bypass tenant isolation. Empty results may mean no matches OR no access — by design, there is no distinction.